Skip to main content

CLI and hooks

surreal-memory-server is one binary with a few subcommands. With no subcommand it serves.

CommandDoes
surreal-memory-serverserve REST, A2A and MCP (and stdio MCP unless MCP_STDIO=false)
surreal-memory-server --versionprint surreal-memory-server <version>
surreal-memory-server repair-data [--dry-run|--apply]inspect or repair legacy enum data
surreal-memory-server embedding-executorrun as the supervised embedding worker (started for you)
surreal-memory-server hook <event>Claude Code hook client
surreal-memory-server statuslineClaude Code status line client

Claude Code hooks​

The hook and statusline commands connect the memory server to Claude Code so a session starts with recalled context and ends by saving its state. They talk only to a running server over HTTP, so they start instantly and never pay for a database or model start.

They fail open: any problem prints a diagnostic to stderr and the command still exits 0, so a stopped or slow server can never block or break Claude Code.

EventWhat it doesTime budget
hook session-startrecalls memories for the project into the agent's context2.5 s
hook pre-compactsaves a session-state memory through the durable operation ledger2.5 s
hook session-endsaves a session-state memory the same way0.9 s
statuslineprints a one-line health summary0.5 s

The server address comes from SURREAL_MEMORY_URL (default http://localhost:23001). Stored session-state memories are written with the agent ID claude-code.

Wire them up in .claude/settings.json:

{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "surreal-memory-server hook session-start" }] }
],
"PreCompact": [
{ "hooks": [{ "type": "command", "command": "surreal-memory-server hook pre-compact" }] }
],
"SessionEnd": [
{ "hooks": [{ "type": "command", "command": "surreal-memory-server hook session-end" }] }
]
},
"statusLine": { "type": "command", "command": "surreal-memory-server statusline" }
}
export SURREAL_MEMORY_URL=http://127.0.0.1:3001 # if you did not use the default port

session-start prints a digest, at most about 1,500 tokens and 8 items, each trimmed:

## Recalled context (surreal-memory)
- [2026-10-27 · semantic · @project] Deploys go out on Fridays after the freeze check passes …
- [2026-08-03 · procedural · @project] When the migration step times out, re-run it with --apply …

and statusline prints, for example:

Ψ ok · 12 ops

:::warning Local mode only These commands send no credential. Against a server running with AUTH_MODE=jwt they get 401 and, being fail-open, quietly do nothing. Use them with a loopback AUTH_MODE=local server. :::

Repairing legacy data​

repair-data normalizes enum values that older versions wrote as single-key objects ({ Active: {} }) into strings. Run the dry run first; it changes nothing:

surreal-memory-server repair-data --dry-run
surreal-memory-server repair-data --apply

Any other argument prints Usage: surreal-memory-server repair-data [--dry-run|--apply].