@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, is a newer version published?). Secrets are rejected on every write. Your memories never leave your machine (only short query/record text transits when embeddings are enabled).

Native modules — no install script needed

Uses better-sqlite3 (native), but nothing is built on your machine and no install script runs. The addon ships prebuilt in a platform package (@prom.codes/native-<platform>) listed as an optional dependency: npm picks the one matching your os/cpu/libc and installs it by copying files. So a hardened npm needs no special handling — ignore-scripts=true (a sensible policy, and npm v12's default) has nothing left to suppress:

npm install -g @prom.codes/memory-mcp

Prebuilt for macOS / Linux (glibc + musl) / Windows on x64 + arm64, Node 22, 24, 25 and 26. Requires Node ≥ 22 — upstream better-sqlite3 publishes no prebuild for Node 20's ABI. On an unshipped combination the install still succeeds and falls back to building from source, which needs install scripts allowed (--allow-scripts=better-sqlite3) and C/C++ build tools.

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