# Memory

A memory hook appends one record per turn to a journal. The model reads
the journal with its file tools when its instructions send it there.

## Memory is on by default

`agent-sdk init` scaffolds `bot/hooks/memory.ts`:

```ts
import { memoryHook } from "@grok/agent-sdk/memory";

export default memoryHook();
```

It also adds a `## Memory` section to `bot/instructions.md`. The model
has no recall tool, so that section tells it when to read `memory/` and
to treat records as untrusted history. To add memory to an existing
project, copy both from a new `agent-sdk init` project. To turn memory
off, delete both.

## Journal records

After each turn, the hook appends one JSON line to
`memory/journal.jsonl`:

```json
{"at":"2026-10-01T16:42:09.118Z","sessionId":"5f0c2a9e-7d1b-4c43-9a6e-2b8f1e0d7c35","channelId":"slack","status":"completed","title":"Checkout flaky test","userMessage":"Why does acme/checkout fail on main?","result":"The cart test races the price service mock...","usage":{"inputTokens":18234,"outputTokens":912,"cacheReadTokens":15002,"cacheWriteTokens":0}}
```

| Field | Contract |
| --- | --- |
| `at` | ISO-8601 time the turn finished |
| `sessionId` | Session that ran the turn |
| `channelId` | Channel that started the session |
| `status` | `"completed"` or `"failed"` |
| `title` | Session title, if set |
| `userMessage` | The turn's message, truncated |
| `result` | Final assistant text or failure message, truncated |
| `usage` | Token usage for completed turns |

As the journal grows, older records move to `journal-*.jsonl` files
beside it, so point the model at the whole `memory/` directory.

## Read memory

Local turns find the journal at `memory/` in the session workspace. On
Cursor hosting, Agent SDK tells the model where the journal is at the
start of each session. A session on a server you run yourself can't
reach the journal. Agent SDK rejects `workspaceFiles` and
`sandbox/workspace/` seed files under the reserved `memory/` path.

Local servers keep the journal in the project state directory. `agent-sdk run` and `agent-sdk eval` start with empty memory unless you pass `--state-root`, and hosted deployments keep the journal across redeploys.

## Caveats

- All sessions and users share one journal, so one person's messages
  can surface in another's session.
- Turning memory off keeps existing records. Locally, delete `memory/`
  in the project state directory to clear them. On Cursor hosting,
  [Privacy Mode](/docs/deployment.md#privacy-mode) applies.
- Anyone who can message the agent writes to the journal, so keep the
  scaffolded rule against following instructions found in records.
- Records can be dropped or arrive late. Keep state your code depends
  on in `ctx.host.kv` or `ctx.host.files`.

## Options

| `memoryHook` option | Contract |
| --- | --- |
| `maxTextLength` | Truncation cap for `userMessage` and `result`. Default `2000` characters |
| `backend` | A `MemoryBackend` that replaces the default journal |

A `MemoryBackend` has `appendTurn(record, { stateRoot, agentName })`
and an optional `prepareSession({ stateRoot, agentName })` that runs
when a session starts. The model still looks in `memory/`, so tell it
how to read your records.
