Pantheon Memory¶
🇧🇷 Versão em Português disponível: Leia em Português
Pantheon has three separate context stores. Use the smallest one that fits:
flowchart TD
subgraph L1["📦 Tier 1: Session Checkpoints & Ephemeral State"]
Pers["💾 pantheon-persistence MCP<br/>(persistence.db)"]
Checkpoints["• Context checkpoints (context_save / get)<br/>• Session goals & transient key/values<br/>• Default TTL: 4 hours"]
Pers --- Checkpoints
end
subgraph L2["🧠 Tier 2: Durable Factual Memory (Long-Term)"]
Mem["SQLite FTS5 / BM25 (memory.db)"]
Facts["• Reusable project decisions & facts<br/>• Capped at 64 KiB per entry<br/>• Lexical BM25 search without vector overhead"]
Mem --- Facts
end
subgraph L3["📂 Tier 3: Human-Reviewed On-Disk Memory Bank"]
Bank[".pantheon/memory-bank/"]
Files["• ADRs (Architecture Decision Records)<br/>• Sprint & product context<br/>• Git-tracked files read on demand via pantheon-resources"]
Bank --- Files
end
Agents["🤖 Specialist Agents"] -->|"Phase state"| L1
Agents -->|"Fast fact retrieval"| L2
Agents -->|"On-demand reading"| L3
| Store | Lifetime | Use |
|---|---|---|
pantheon-memory MCP |
SQLite memory.db; entries are capped at 64 KiB serialized by default and expire only when stored with ttl_seconds (expired entries are hidden from search and purged explicitly) |
Reusable project facts and decisions |
pantheon-persistence MCP |
Separate SQLite store; session-qualified context checkpoints default to 4h (heartbeat: 5m) | Explicit checkpoints and temporary key/value data |
.pantheon/memory-bank/ |
Project files in the working tree; Git tracking depends on repository ignore/commit policy | Human-reviewed project context and ADRs |
External MCP providers, such as flashmemory, use stores separate from
Pantheon's pantheon-memory SQLite database. Using the same namespace string
does not share or synchronize entries. External providers define their own
retention, TTL, and write semantics; consult the relevant provider and version
documentation for those behaviors.
These stores are not automatically synchronized. In particular, compaction's
TODO preservation is process-local and does not write to pantheon-persistence.
The context_* persistence tools are optional MCP checkpoints, not automatic
compaction hooks. They are separate from durable pantheon-memory entries:
checkpoint namespaces include the session ID, with the defaults shown above.
See Persistence checkpoints and
Manual session goals.
Pantheon does not implement OpenCode-style /memories/repo/ or
/memories/session/ stores or automatic loading from those paths. Durable
entries are stored through the pantheon-memory MCP tools. Project documents
under .pantheon/memory-bank/ remain files and are read explicitly, including
through pantheon://memory-bank/{path} from pantheon-resources; that resource
is on-demand, not auto-loaded.
Memory MCP¶
The server stores entries in SQLite and indexes them with FTS5/BM25. Retrieval
is lexical: a query must share words with stored content; there is no embedding
model or vector search. The default namespace is default; use a named
namespace when entries have a distinct owner or purpose.
Namespace is an organizational/search filter, not an access-control boundary;
searches without a namespace filter can return matches from any namespace.
Two limits keep the store from growing without bound:
- Size. A write is refused when the serialized entry —
value,metadata,namespaceandkeyas UTF-8 — exceeds the per-entry cap: 65,536 bytes (64 KiB) by default, the same bound the Persistence MCP applies to checkpoint content. Over-cap entries are rejected, never truncated, because a shortened memory is silent data loss; the error states the actual size, the cap, and the environment variable that raises it. SetPANTHEON_MEMORY_MAX_ENTRY_BYTES=<bytes>in the memory server's environment to change the cap (read per write; any positive integer, and an invalid value falls back to 64 KiB).memory_statsreportstotal_bytes,max_entry_bytes,warning_threshold_bytes(half the cap, minimum 1 byte),oversized_entries(entries over that threshold) and up to fivelargest_entrieswith namespace, key and bytes. - Expiry.
memory_store(ttl_seconds=...)gives an entry a lifetime (1 second to 365 days). Entries stored without it never expire, which is how every older entry behaves.memory_searchhides expired entries by default (include_expired=Trueshows them);memory_recallstill returns an expired entry by exact key, becauseNonewould be indistinguishable from an entry that never existed.memory_list, the maintenance view, also still shows expired rows. Nothing deletes an expired row implicitly:memory_forget(expired_only=True)is the explicit purge and reports how many rows it removed.decay_daysonly changes search ranking; it does not expire data.
Opening an existing database adds the expires_at column automatically when it
is missing; the ALTER TABLE is guarded by a column check, so a second open is a
no-op and existing rows keep working (NULL means "never expires").
| Tool | Use |
|---|---|
memory_search(query, namespace?, top_k?, decay_days?, include_expired?) |
Find relevant entries; use top_k=2 for task context; expired entries are hidden unless include_expired=True |
memory_recall(key, namespace?) |
Fetch an entry when its exact key is already known (ignores expiry) |
memory_store(value, namespace?, key?, metadata?, ttl_seconds?) |
Store a concise, reusable fact or decision; ttl_seconds makes it expire |
memory_forget(id?, key?, namespace?, expired_only?) |
Remove an entry by ID or key, or purge every expired entry with expired_only=True |
memory_list(namespace?, prefix?, limit?) |
Inspect entries during explicit maintenance |
memory_stats() |
Inspect counts, disk usage, payload bytes and the largest entries during explicit maintenance |
metadata must be a JSON object encoded as a string, for example:
metadata='{"type":"decision"}'. A key is unique within its namespace;
duplicate keys fail rather than silently replacing the old entry.
The installed source also exposes the optional code_index, code_query, and
code_neighbors codemap tools. The installer uses src/mcp/memory_mcp.py as
the canonical runtime source; the standalone scripts/memory_mcp.py copy is
intentionally lighter. Keep their differences deliberate.
Recall and compaction policy¶
Memory is available through MCP tools, but agents call it only when it can change the task outcome. This keeps ordinary turns free of duplicate retrieval and prevents compaction from turning into a second persistence workflow.
| Need | Mechanism | When to use |
|---|---|---|
| Find prior decisions or project facts | memory_search |
One focused query when relevant history is missing from the current context; skip self-contained work and weak matches. |
| Resume a task in another session | context_save / context_get |
Save one concise checkpoint when the user requests it or a task is expected to cross sessions and lose needed state; retrieve it when resuming. |
| Preserve a reusable decision across tasks | memory_store through Mnemosyne |
Only when explicitly requested or authorized; store one concise fact, never routine progress or secrets. |
| Reduce the active conversation | Native OpenCode compaction | Let the host summarize the current session under context pressure. Do not call an MCP to summarize each phase or duplicate the compaction summary. |
Use top_k=2 for a targeted recall unless the task needs a broader review. A
checkpoint should preserve the objective, current phase, completed work, next
step, decisions, blockers, and uncertain external outcomes. It should not copy
the transcript, routine tool logs, or speculative results. context_save and
context_get are not automatic compaction hooks and are not needed on every
turn, delegation, or phase boundary.
An old memory_injection setting may remain in a user's plugin options because
installation preserves custom options; the V2 plugin ignores it. Remove that
legacy key if it appears in opencode.json.
Persistence checkpoints¶
The pantheon-persistence MCP server exposes exactly six tools:
context_save, context_get, goal_create, goal_get, goal_update, and
goal_done. The KV table is internal checkpoint storage; the former KV
management/search and context list/statistics/rehydration/summary operations are
not registered.
| Tool | Signature | Use |
|---|---|---|
context_save |
context_save(slug, key, content, session_id, ttl?, scope?, revision?) |
Save a bounded session checkpoint and atomically update latest |
context_get |
context_get(slug, key?, session_id?, legacy?, scope?) |
Read a session-qualified checkpoint; key defaults to latest |
goal_create |
goal_create(title, description?) |
Create the single active manual goal for the session |
goal_get |
goal_get(goal_id?) |
Read the active goal, or the latest completed one |
goal_update |
goal_update(goal_id, expected_version, title?, description?, clear_description?) |
Edit user fields with optimistic version checking |
goal_done |
goal_done(goal_id, expected_version) |
Mark the goal done; repeated completion is idempotent |
scope defaults to "project"; use "global" for checkpoint APIs. Checkpoints
use the namespace checkpoint:{slug}:{session_id}. session_id is required and
is never generated or inferred from slug; the legacy unqualified namespace is
available only through legacy=true on context_get.
context_save commits the checkpoint and its raw latest pointer in one SQLite
BEGIN IMMEDIATE transaction. Caller revision values are monotonic; an older
or equal revision returns status: "stale" without overwriting. Without a
caller revision, persistence assigns a monotonic revision under the write lock.
content is a JSON-encoded string, not a raw object: callers pass
JSON.stringify(state). The decoded top level must be an object; inside it,
goal, phase, delegations (with in_flight), and heartbeat are objects
and tail is an array. goal is optional — omit it rather than sending a
placeholder. Invalid JSON or shape fails closed. Save-side bounds are:
content: at most 65,536 UTF-8 bytes.tail: at most 100 strings, each at most 4,096 UTF-8 bytes, at most 65,536 UTF-8 bytes in aggregate.ttl: an integer from 1 to 31,536,000 seconds. Omitted values default to 300 seconds forheartbeatand 14,400 seconds for other context keys.
Over-limit data is rejected, not truncated; shorten it or omit the optional
tail.
Manual session goals¶
The four goal_* tools are a direct, manual feature of the Persistence MCP;
they do not add a V2 plugin proxy or another goal database. Canonical agent
frontmatter grants them only to Zeus. All other agents are denied.
Goals are partitioned by OpenCode session id inside the Persistence deployment
database; in a global install, projects share that database. FastMCP 4.1.2
handlers read the session id from
Context.request_context.meta["ai.opencode/sessionID"]. Missing, malformed, or
invalid metadata fails closed. The session id is a correlation/scope key, not
authentication. The supported trust boundary is OpenCode 2.x-mediated local
stdio (measured on 2.0.30); do not expose the server over HTTP or another
network transport.
There is one active goal per session. A completed goal stays in history and a
new one can be created after completion. Status, timestamps, and a monotonically
increasing version are server-owned. Pass the version from goal_get as
expected_version; a stale write returns a conflict. goal_done cannot reopen a
goal, and repeated completion is idempotent. Outputs contain only the goal id,
editable text, status, timestamps, and version — not the session id, database
path, or SQL.
These are manual records only. They do not migrate or replace the V1
src/pantheon/goal-store.ts authority, write to it, or trigger continuation,
reinjection, an evaluator, loop, board, TUI/RPC, or ctx.storage. The V1 JSON
store at .pantheon/goals/*.json is untouched and not imported. The V2 plugin's
own goal tools remain unsupported.
A pristine Persistence project database is initialized with both the
checkpoint and goal schemas. If the project database already contains user
schema, startup performs no goal-schema DDL. Users who do not use the goal tools
need do nothing; only users who want them on an existing project database need
the explicit, human-run migration. When the schema is absent, the goal tools
fail closed and return the exact command
<venv-python> <installed-script> --migrate-goals. Skipping migration leaves
checkpoint tools working and goal tools unavailable, without data loss.
The migration target is the Persistence project database only — never
global.db, and never the V1 goal store. Before changing schema it makes and
verifies an adjacent, timestamped full copy with mode 0600; an already-current
schema needs no backup. To migrate safely:
- Stop the Persistence server and keep it stopped.
- Read the configured
pantheon-persistenceMCP entry. Use itscommand[0]interpreter and resolve the script againstcwd; preservePANTHEON_PROJECTif set. An explicit--project-dbtakes precedence overPANTHEON_PROJECT, which takes precedence over the runtime target. - Run the returned command with
--migrate-goals --dry-runand confirm the resolved path is the intended project database. - Run the same command without
--dry-run.
The migration is idempotent. If the schema is inconsistent (for example, a migration row without its table, or a table missing an index), stop and recover from a verified backup rather than rerunning blindly. Backups live beside the selected database; a runtime-default directory may be replaced by uninstall/reinstall, so move backups you need outside it. Retention is manual.
Low-call policy¶
- Search only when project history could change the answer or implementation. Skip it for self-contained questions and small, obvious fixes.
- In delegated work, search at most once at the coordinator level and include useful results with the task. A specialist searches separately only if that context is missing and relevant.
- Do not search and then immediately recall the same result. Use
memory_recallonly when the exact key is known without a search. - Store no routine child summaries, phase updates, test logs, or temporary state. At most one concise, top-level reusable outcome should be stored when it will matter in a later session.
- Never store secrets, credentials, or tokens.
memory_storestores submitted values and metadata; automatic secret scrubbing/redaction is not guaranteed, so omit sensitive content or redact it before storage. - Do not claim automatic persistence or recovery: a store is durable only after
memory_storereports success.
Memory Bank files are not automatically synchronized or cross-clone persistent.
In particular, .pantheon/memory-bank/_tasks/ records may be Git-ignored;
whether any Memory Bank file is shared depends on the repository's ignore and
commit policy.
For the full tool catalog, see MCP tools. MCP server setup and allowlists are in MCP.