Memory model

The context engine answers "what does this codebase look like now?" The memory server answers "what did we already learn, decide, and agree on?" — and keeps that knowledge across context-window resets and agent restarts. This page describes the data model behind @prom.codes/memory-mcp; for setup and the tool surface see Agent Memory.

The scope chain

Every record is filed under one of four scopes, ordered narrowest to broadest:

project → workspace → tenant → system

Recall walks that chain. When two records share the same type and key, the narrowest scope wins: a project-level fact overrides a workspace default, which overrides a tenant or system default. That is the team-default vs project-override framing — broad scopes carry the team's shared conventions, and any single project can locally override them without touching the team record. Episodic records (see below) are keyed per session, so they never collide and never override one another.

In the local-first Phase 1, project-scoped records are keyed by the project identity (a hash of PROMETHEUS_WORKSPACE_ROOT), and the broader scopes collapse to a single global bucket until multi-tenant team sync lands in a later phase. The resolution rules are scope-aware from day one, so the same records and the same logic carry forward unchanged when sync arrives.

The four memory types

memory_capture at session end turns a session's plan/outcome into an episodic record, repeatedly confirmed statements into semantic facts, and successful tool sequences into procedural records.

Local-first storage

All records live in one SQLite database on your machine (~/.prometheus/memory.db by default, overridable with PROMETHEUS_MEMORY_DB_PATH), partitioned per project. Nothing is uploaded; the same PROMETHEUS_API_KEY that unlocks the context engine unlocks memory, and in the local-first default the memory server makes no network calls at all.

Project-scoped facts are additionally mirrored to git-versioned markdown under <workspace-root>/.prometheus/memories/*.md — plain, human-editable, reviewable in pull requests, shared with the team through git. The markdown files are the canonical source: memory_read syncs them back into the database (as project-scoped semantic records) before resolving, so the mirror never drifts. Deleting a record removes its markdown file too.

Secrets are rejected on write

Before a value reaches the database or a markdown file it is scanned against a deny-list of secret shapes — provider API keys (OpenAI, Anthropic, Supabase, GitHub, Vercel, RunPod, Hugging Face, …), JWTs, AWS access keys, private-key blocks, Authorization headers, and connection strings with inline credentials. A match is refused outright. The error names only the matched pattern, never the value, so memory never becomes a place a secret leaks into git or a transcript.

Token-capped recall

memory_read doesn't return raw rows — it resolves the scope chain, then weave()s the surviving facts and procedures into a single prompt-ready markdown block under a hard token budget (≈1,500 tokens by default). Facts are ordered by confidence, then use-count, then recency; procedures by use-count then recency. Records are packed greedily and the block stops at the cap, so memory delivers the most relevant knowledge without crowding out the rest of the prompt.