@prom.codes/memory-mcp

prom.codes Memory — persistent, local-first agent memory as an MCP server (stdio).

Gives coding agents a durable memory across sessions: facts, decisions and procedures survive context-window resets. Records live in a local SQLite database (~/.prometheus/memory.db); project-scoped memories are mirrored as git-versioned markdown under .prometheus/memories/ in your repo.

Quick start (Claude Code)

claude mcp add memory --env PROMETHEUS_API_KEY=prom_live_… -- npx -y @prom.codes/memory-mcp@latest

Docks under the server name memory, so tools resolve to memory_read / memory_write / … claude mcp add defaults to local scope; add --scope project for a committable .mcp.json. Other hosts (Cursor, VS Code) use the same command/args in their own config.

Awareness — so the agent actually uses memory. A server only offers tools; the agent uses them only if told to. On startup the server auto-installs a marked memory-protocol rule block into the runtime config files you already have (CLAUDE.md / AGENTS.md / .cursor / .augment) — idempotent, never creates a new file, skipped for home/root, opt out with PROMETHEUS_MEMORY_AUTO_SETUP=off. Those files load every session, so the agent reads memory at session start, writes durable facts as they come up, and captures at the end — without being asked. Run memory_setup to install into all detected runtimes (incl. creating AGENTS.md if you have no config yet); memory_status shows what's installed.

Configuration

• Works with no key at all — boots keyword-only (FTS5) and fully offline. A PROMETHEUS_API_KEY (real prom_live_<tag>_<secret> from app.prom.codes/app/api-keys) adds semantic recall via the managed proxy — the same one key as Context and Saver.
• Workspace root is auto-detected (Claude Code CLAUDE_PROJECT_DIR / MCP roots) — no need to set PROMETHEUS_WORKSPACE_ROOT.
• Optional quality levers (documented): PROMETHEUS_MEMORY_RERANK_PROVIDER (cross-encoder rerank — reranked recall ties full-context at ~28× fewer tokens on LoCoMo), PROMETHEUS_MEMORY_REWRITE_PROVIDER (HyDE), and PROMETHEUS_MEMORY_DEDUP=on (collapse restatements so distinct facts fill the top-k). Temporal-intent ranking ("latest/earliest" queries) is on by default; disable with PROMETHEUS_MEMORY_TEMPORAL=off.

If a fresh window opens with no project, the workspace falls back to the host cwd (often home); in that case memory still works but project memories are NOT mirrored to markdown there and memory_setup refuses to write rule files into your home dir. Open a project folder so memories scope correctly.

Tools (docked as memory): memory_read, memory_write, memory_capture, memory_search, memory_list, memory_delete, memory_setup, memory_status (health check: which folder, how many records, does the key work?). Secrets are rejected on every write. Your memories never leave your machine (only short query/record text transits when embeddings are enabled).

Native modules

Uses better-sqlite3 (native). Prebuilt binaries are fetched automatically on common platforms (macOS x64/arm64, Linux x64/arm64, Windows x64) — no compiler needed. On an unsupported platform/Node ABI, install C/C++ build tools so the module can compile (Windows: VS Build Tools). Requires Node ≥ 20.10.

Docs: https://prom.codes/docs/mcp/memory