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:

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:

{"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 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.