Concepts

Session recorder

What the opt-in Session Recorder captures, how it protects secrets, where it stores data (locally, never uploaded), and how to turn it off.

The Session Recorder is an opt-in, local-first feature of @prom.codes/memory-mcp that captures your coding sessions so the memory server can answer "what did I do this week?" and "have we tried this before?" — and, later, distil durable knowledge from how you actually work.

It is off by default. Nothing is recorded until you explicitly install it, and nothing it records ever leaves your machine.

What it is

When you run the recorder_setup tool, memory-mcp installs five Claude Code hooks. Each hook appends one line to an append-only local file; the running memory-mcp server ingests those files into its local SQLite database.

Claude Code ──hook──▶ prometheus-recorder-hook.mjs ──append──▶ ~/.prometheus/recorder/…jsonl
                        (pure Node, no deps)                         │
                                                                    ▼ ingested by
                                                       memory-mcp  (local SQLite)

There is no server, no streaming, and no network call in this path. Raw session data is written to disk on your machine and read back by the local memory server. (The only network calls memory-mcp ever makes are optional embeddings/curation through the metered proxy — never the raw recorder stream.)

What it stores — behaviour, not code

The recorder captures what you did, not a full transcript. Every event is put on a strict payload diet:

Hook	Captured
`SessionStart`	working directory, model
`UserPromptSubmit`	your prompt text
`PostToolUse`	tool name + a short preview — see below
`Stop` (per turn)	the assistant's last message of the turn
`SessionEnd`	end reason; stats are computed at ingest

Tool previews are deliberately small:

Edit / Write: the file path + a 100-character preview of the old/new text — never a full diff.
Bash: the command (≤300 chars) + stdout (≤500) + stderr (≤200) + exit code.
Read / Glob / Grep: only the path or pattern — no file contents.
Everything else: a ≤500-character preview of the result.

Each event is hard-capped at 4 KB, and each session's spool at 4 MB (after which further tool events are dropped, keeping your and the assistant's messages). File contents are never uploaded — your code index already knows the code; the recorder stores behaviour.

Secret protection (three layers)

The hook redacts obvious secrets (API keys, tokens, private keys, connection strings, JWTs) to [redacted] before anything is written.
The ingest re-scans every line; anything that still matches is stored as [dropped: secret-like] — never the value, and never silently discarded.
Sensitive files are skipped entirely: the contents of .env*, *.pem, *.key, id_rsa, and paths under secrets/ or credentials/ are never captured — only the fact that such a file was touched.

Where it lives & how long

Location: ~/.prometheus/recorder/ (spool) and your local memory database (~/.prometheus/memory.db). Both are on your machine only.
Retention: events are kept for 90 days or the 300 most-recent sessions per project, whichever comes first. Tune with PROMETHEUS_RECORDER_RETENTION_DAYS / PROMETHEUS_RECORDER_MAX_SESSIONS.

From sessions to durable memory (curation)

Recording is only half the value. When an extraction model is configured (PROMETHEUS_MEMORY_EXTRACT_PROVIDER = mistral / openai / generic), memory-mcp curates finished sessions: a second prompt distils each session's log into a short summary plus fact and procedure candidates. This runs automatically after a session ends, or on demand via the curate tool.

Curated candidates flow through the normal memory-write path, so project-scoped facts land in .prometheus/memories/ — git-versioned and reviewable in a pull request before they become team knowledge. Each candidate is secret-scanned independently and dropped if it looks sensitive. Without an extractor configured, curation is simply inactive; the raw recorder still works through sessions and search.

Turning it on and off

On: run the recorder_setup tool (scope project-local by default — this project only; user records across all your projects). Reload your Claude Code window afterward.
Off: run recorder_setup with { uninstall: true }. The hooks are removed and settings.json is restored (it was backed up on install).
Browse what's stored: the sessions tool (list / get) and search with sources: ["sessions"]. status shows whether the recorder is installed and how much is stored.

A recorder problem can never break a coding session: every hook catches all errors and exits cleanly. And because it is opt-in and local, you stay in full control of your own data — consistent with Prometheus' sovereignty guarantee.