> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linksee.app/llms.txt
> Use this file to discover all available pages before exploring further.

# remember

> Save, update, or delete memories — unified tool for all write operations

Save, update, or delete memories that persist across sessions and across AI agents. This is the **unified write tool** — it handles create, update, and delete operations based on which parameters you provide.

Memories saved here are accessible from **any** AI agent the user connects to — Claude, GPT, Cursor, Codex, Gemini.

<Info>
  **v0.7.0**: `remember` replaces the previous `remember` + `update_memory` + `forget` tools. Mode is auto-detected from params.
</Info>

## Modes

### Create (default)

Provide `entity_name` + `entity_kind` + `layer` + `content`:

```json theme={null}
{
  "entity_name": "KanseiLink",
  "entity_kind": "project",
  "layer": "caveat",
  "content": "{\"title\":\"freee OAuth Friday deploy\",\"what\":\"Never deploy freee OAuth changes on Friday\",\"why\":\"Their sandbox goes down for maintenance every Friday night JST\"}",
  "importance": 0.95
}
```

### Update

Provide `memory_id` + fields to change:

```json theme={null}
{
  "memory_id": 42,
  "content": "Updated caveat: verified again 2026-05, still applies",
  "importance": 0.95
}
```

Preserves `memory_id` and `session_file_edits` links. Preferred over delete + create.

### Delete

Set `forget: true` + `memory_id`:

```json theme={null}
{
  "forget": true,
  "memory_id": 42
}
```

Caveat-layer and pinned memories (importance >= 0.9) are protected and cannot be deleted.

## Parameters

### Create mode (required)

<ParamField body="entity_name" type="string" required>
  Name of the entity this memory is about (e.g. "MyProject", "Supabase", "Alice").
</ParamField>

<ParamField body="entity_kind" type="string" required>
  One of: `person`, `company`, `project`, `concept`, `file`, `other`.
</ParamField>

<ParamField body="layer" type="string" required>
  Memory layer. One of: `goal`, `context`, `emotion`, `implementation`, `caveat`, `learning`.

  Common aliases are accepted:

  | Alias                                | Resolves to      |
  | ------------------------------------ | ---------------- |
  | `why`, `intent`, `targets`           | `goal`           |
  | `background`, `reason`, `timing`     | `context`        |
  | `tone`, `feelings`, `mood`           | `emotion`        |
  | `impl`, `how`, `tried`               | `implementation` |
  | `warning`, `pain`, `pitfall`, `dont` | `caveat`         |
  | `decision`, `insight`, `growth`      | `learning`       |
</ParamField>

<ParamField body="content" type="string" required>
  The memory content. Plain text or JSON with structured axes (title, altitude, type, state, what, why, affects, next\_action).
</ParamField>

### Optional (all modes)

<ParamField body="importance" type="number">
  `0.0` to `1.0`. Set to **0.9 or higher to pin** a memory — pinned memories are protected from auto-forgetting even outside the caveat layer. Default: auto-assigned based on layer.
</ParamField>

<ParamField body="thread_id" type="string">
  Optional thread ID to group related memories (e.g. a session ID or decision chain). Enables decision -> implementation -> outcome tracing.
</ParamField>

<ParamField body="force" type="boolean" default="false">
  Bypass the paste-back quality check. Set `true` only when you are sure the content is original user or agent thought, not pasted CI logs or assistant output.
</ParamField>

### Update mode

<ParamField body="memory_id" type="number">
  The `memory.id` to update. Get this from a prior `recall` response. When provided without `forget: true`, enters update mode.
</ParamField>

### Delete mode

<ParamField body="forget" type="boolean" default="false">
  Set `true` with a `memory_id` to delete that memory.
</ParamField>

## Behavior

1. **Entity resolution**: 3-tier matching — canonical\_key exact -> normalized\_name -> case-insensitive name -> insert new entity
2. **Quality check**: Rejects pasted CI logs, assistant output, and other non-original content (bypass with `force: true`)
3. **Auto-structuring**: Plain text is wrapped into structured JSON with inferred `altitude`, `type`, and `state` classifications
4. **Pinning**: Memories with `importance >= 0.9` get `protected = 1`, preventing auto-forgetting
5. **Events**: Records a `memory_stored` event for momentum tracking

<Warning>
  Caveat-layer memories are **always protected** regardless of importance score. They survive consolidation and auto-forgetting indefinitely.
</Warning>

## Migration from pre-v0.7

| Old call                                           | New equivalent                                                    |
| -------------------------------------------------- | ----------------------------------------------------------------- |
| `update_memory({ memory_id: 42, content: "..." })` | `remember({ memory_id: 42, content: "..." })`                     |
| `forget({ memory_id: 42 })`                        | `remember({ forget: true, memory_id: 42 })`                       |
| `forget({ dry_run: true })`                        | No longer exposed — auto-consolidation handles cleanup on startup |