Recorder Companion

cerememory-recorder is an optional, opt-in companion binary that preserves observed agent and tool events in the Cerememory raw journal. The core database stays focused on memory storage; the recorder normalizes Capture Events, applies safety guards, and posts batches to the Cerememory HTTP API.

It does not execute tools, plan work, run MCP clients, or promote raw material into semantic memory. Curation remains the job of dream_tick.

What The Recorder Does

Capture Event JSONL

ingest reads one JSON object per line from stdin.

Required fields

Optional fields

Supported event_type values

• user_message
• assistant_message
• tool_call
• tool_result
• command
• file_change
• session_summary
• error

{"session_id":"codex-2026-04-28","event_type":"user_message","content":"Investigate the failing recorder test","source":"codex","metadata":{"cwd":"/repo"}}

ingest

Start a Cerememory HTTP server first, then pipe Capture Event JSONL into the recorder.

cerememory serve --port 8420
 
printf '%s\n' '{"session_id":"demo","event_type":"user_message","content":"hello recorder"}' \
  | cerememory-recorder ingest --server-url http://127.0.0.1:8420

If the server requires HTTP auth, set the API key through the environment so it never appears in ps output or shell history:

export CEREMEMORY_SERVER_API_KEY='...'

Spool And Retry

ingest posts to /v1/encode/raw/batch. Failed batches are written as recorder-owned batch-*.jsonl files under ~/.cerememory/recorder/spool after redaction has been applied.

On Unix the spool directory is created with 0700 and spool files with 0600. The recorder refuses to chmod an arbitrary pre-existing directory - it must already be private. A subsequent ingest run flushes any pending recorder-owned spool files before reading new stdin.

Codex Hook Helper

install-hook codex generates a non-destructive helper script and example config so a Codex CLI session can stream events into the recorder.

cerememory-recorder install-hook codex --server-url http://127.0.0.1:8420

The command writes:

• .codex/hooks/cerememory-recorder-codex-hook.py
• .codex/hooks/cerememory-recorder.example.json

It checks both target paths before writing either file and refuses symlink targets (including with --force). Existing files are not overwritten unless --force is passed. The installer does not edit your existing Codex hook settings - copy the generated command into the hook configuration you choose to use and provide CEREMEMORY_SERVER_API_KEY through the shell or hook environment if upstream auth is enabled.

Event mapping in the generated hook

doctor

Run diagnostics against the HTTP server.

cerememory-recorder doctor --server-url http://127.0.0.1:8420

doctor checks:

• GET /health
• GET /readiness
• spool directory writability
• authenticated raw batch ingest

The raw ingest check writes a small private_scratch probe record so it can distinguish connectivity, auth, rate-limit, and server failures. Use --skip-raw-ingest-probe when a non-mutating check is required - in that mode the recorder verifies auth with a limit=0 raw recall probe instead of writing a raw journal record.

cerememory-recorder doctor --server-url http://127.0.0.1:8420 --skip-raw-ingest-probe

Safety Defaults

• visibility defaults to normal.
• secrecy_level defaults to sensitive.
• JSONL lines larger than 256 KiB are rejected before parsing, including surrounding whitespace.
• Recent duplicate events are dropped only when they carry an explicit turn_id, action_id, or timestamp identity and the same content.
• Obvious bearer/basic auth headers, API keys, tokens, cookies, client secrets, private-key blocks, passwords, and common token shapes are redacted from text, metadata, and caller-supplied meta before sending or spooling.
• Caller-supplied meta is forwarded only when present; the recorder does not invent MetaMemory intent or rationale.

Mental Model

1. MCP connection alone records nothing. The proxy only forwards explicit tool calls.
2. A hook (or adapter) emits Capture Events in JSONL and pipes them to cerememory-recorder ingest.
3. The recorder redacts, normalizes, and POSTs them to /v1/encode/raw/batch.
4. The server writes raw journal entries. These are not curated memories yet.
5. dream_tick later promotes appropriate raw entries into episodic and semantic memory, respecting secrecy_level.

Next Steps