Skip to main content
Curated memory facts are short, human-reviewable truths committed in your repository: operator corrections, working agreements, non-obvious project facts. They are repo-owned, so every managed harness (Claude Code, Codex, Pi, ACP, OpenCode, Grok, Kimi Code, Muse, Prime Agent) sees the same list, on every machine, after a normal git pull. This is distinct from Claude Code’s own per-machine auto-memory, which Overdeck does not read.

What a fact is

One markdown file with YAML frontmatter, named <id>.md:
Frontmatter keys Overdeck does not know are kept: pan memory edit and a supersession rewrite write them back unchanged, after the known keys. An invalid created, status, supersedes, superseded_by or source value makes the file a problem that pan memory list reports, the same as an invalid updated. type: user is valid only in the operator and machine stores (below). The id must match /^[a-z0-9][a-z0-9-]{0,79}$/. A project-store or operator-store fact whose title, description, tags, or body contains a machine-specific path (an absolute path into a home directory) is refused; see Several machines below.

Where facts live

  • Project store: <planHome>/.overdeck/memory/, one file per fact, committed on your code branch. For a single repository, planHome is the project root. For a polyrepo, it is the repository your project nominates as its plan home (pan_records.repo).
  • Operator store (--user): ~/.overdeck/context/memory/. This is where “who the operator is” facts live. It travels with you: once you run pan memory sync --setup <git-url>, it is synced across your machines (see Syncing operator memory below). It refuses home-directory paths whether or not it is synced.
  • Machine store (--machine): ~/.overdeck/context/machine-memory/, this machine only, never synced. It is the only store that accepts home-directory paths, so facts about local paths and hardware go here.
All three stores are flat directories. A README.md, a dotfile, a subdirectory, or a non-.md file is ignored, so a human README can sit alongside the facts.

How agents see them

Every managed launch injects a rendered index, right after the project layer and before the workspace section:
The operator section follows immediately with the heading ## Operator memory, and the same shape. Its source line says whether the store is synced: synced across your machines by pan memory sync, or not synced; pan memory sync --setup <git-url> shares it across machines. The machine section comes last, with the heading ## Machine memory and the source line this machine only, never synced. Nothing is stored: the index is rendered from frontmatter fresh at every launch, and a launch never touches git or the network. always facts lead the list; among those and among the rest, order is by type (feedback, project, reference, user), then by updated descending, then by id. The project section is bounded at 12,000 characters, the operator section at 4,000, and the machine section at 2,000; once the budget is reached, the index stops and prints how many more facts to find with pan memory list (--user, --machine). A fact carrying a non-empty review marker is never injected; only pan memory list --review shows it. The index and pan memory search also leave out a fact with status: superseded or status: retired, and any fact that names a superseded_by, whatever its status says. pan memory list hides them too; pan memory list --all shows every fact, ending each inactive line with [superseded by <id>], [superseded], [retired] or [review: <markers>]. Only the index line is injected; open the fact file (pan memory show <id>) for its body. A fact added inside a workspace reaches every session’s index once its branch merges and the primary checkout pulls, not the agent’s own next session inside that same workspace.

Prompt-time retrieval

The launch index above is budget-cut, so a large store can omit a fact’s index line entirely. Beyond that index, Claude Code’s, Codex app-server’s and Pi’s per-turn prompts, and every agent’s first prompt, also rank the active, non-always facts across all three stores against the prompt and inject up to 6 of them, each with its description and body, under a shared 1,500-token budget, so a fact the launch index cut can still reach the turn that names its topic. An always fact is never a retrieval candidate; it only ever reaches an agent through the launch index, where it always sorts first (see Adding and curating facts below). Launch budgets and the overflow line are unchanged. Every retrieval decision is logged to rag-runs alongside the other prompt-time candidate groups.

Adding and curating facts

See pan memory for the full option reference. Writes land in your checkout; the PR is the review. add, edit, and retire write into the checkout that owns your current directory (or --project <key>’s primary checkout, --user for the operator store, or --machine for the machine store) and print the git add/git rm plus commit command to run for a project fact. Overdeck never commits a project fact for you. A --user write to a synced operator store runs one sync and prints its outcome; the fact is written even when that sync is offline. add --type user without --user or --machine is refused: user facts belong in the operator store. A fact whose text trips the secret scanner (an API key, a token: value pair) is refused with no file written; rephrase it. If .overdeck/ is gitignored in your project, add refuses with the exact line to add to .gitignore. add --always and edit <id> --always/--no-always set or clear the always flag described in Prompt-time retrieval above:
After a successful write, add and edit also refresh that store’s entry in the fact vector cache (~/.overdeck/cache/memory-fact-vectors.json, one file shared by every store) best-effort: a failure or timeout prints vector index not refreshed: <reason>; run pan memory reindex to stderr without changing the exit code or the written fact. Run it by hand, or after a bulk edit outside pan memory, with:
reindex refreshes the project store (the same one add/list use, or --project <key>’s), the operator store, and the machine store, printing one <scope>: <embedded> embedded, <reused> reused line per store (or --json’s { stores: [...] }). Unlike the best-effort refresh after a write, it exits 1 when embedding fails; it is the way you confirm the cache is healthy. Outside a registered project with no --project, it skips the project store with a note rather than failing. pan memory sync also refreshes the operator store’s vectors, best-effort, after a synced outcome. Pass --source <text> to add or edit to record who or what made the rule, and when, for example --source "twitch:alice 2026-11-10 14:20". pan memory show prints it as Attribution:, followed by Created:, Status: and Supersedes: lines when the fact has those values.

Replacing a fact

When a new rule replaces an old one, link them instead of deleting the old fact:
The new fact gets supersedes: [<old>]. The old file stays on disk: it is rewritten with status: superseded, superseded_by: <new> and today’s updated, every other field kept, and it leaves the index and search at once. --supersedes takes a comma-separated list, and edit adds to the fact’s existing list. Every file is checked before any is written, and nothing is written when:
  • a named fact is not in the same store (no fact "<id>" in <dir>), or its file cannot be parsed;
  • the fact names itself (a fact cannot supersede itself);
  • a named fact is already superseded by a different fact ("<old>" is already superseded by "<other>");
  • with edit, the edited fact is itself superseded ("<id>" is superseded by "<other>"; edit that fact instead).
Naming a fact that this fact already supersedes changes nothing for it. For a project fact, commit both files: the printed git add hint names every file written. There is no undo flag; to undo a supersession, edit both files by hand (remove status and superseded_by from the old fact and the id from the new fact’s supersedes). pan memory lint flags a link that is only half undone. pan memory retire <id> is still the hard delete, with git history as the archive. A fact you mark status: retired by hand stays on disk and out of the index.

Linting facts

pan memory lint reads one store (chosen like list: --project <key>, --user, --machine or --here) and prints an advisory report. It never edits a fact, and it exits 0 after any report; it exits 1 only for an invalid flag or a store it cannot resolve.
The report has three sections:
  • Links: supersession problems: an id that names no fact, a link recorded on only one side, a status: superseded without superseded_by (or the reverse), a supersession cycle, and an active fact whose description says it is superseded, with the pan memory edit <new> --supersedes <id> to run.
  • Duplicates: pairs of active facts at or above the duplicate similarity threshold.
  • Contradictions: pairs of active facts the memory extraction provider judges to conflict.
Similarity uses the conversation-search embedding provider when it is enabled and has a key (duplicate threshold 0.90). Without an embedding provider, or when it fails, lint falls back to lexical similarity, a local word-overlap score (duplicate threshold 0.60), and names the reason. --threshold <n> (0 to 1) overrides the duplicate threshold. The contradiction pass asks the memory extraction provider about at most 20 of the most similar pairs; --no-llm skips it, and an unavailable provider is reported, not fatal. Superseded and retired facts are left out of the duplicate and contradiction checks, because a fact and its replacement are similar by design. --json prints the whole report. pan memory search <query> prints matching curated facts first, under Project memory:, Operator memory: and Machine memory: headings, before the usual observation hits below them. --json output is unchanged: it is still the observation array only. Pass --facts with --json to get both at once, as a single line of JSON: pan memory search "release" --facts --json prints { facts, observations }. facts holds up to 5 matches from each store: this checkout’s project store (the one add writes), the operator store and the machine store. Each match is { scope, type, id, title, description, tags, file } with no body. observations holds the same matches as plain --json, trimmed to a short form without the full narrative. Without a scope flag (--project, --workspace, --issue, --global), observations are scoped to the project that owns your current directory, falling back to --global when it owns none. --facts without --json exits 1.

Facts vs. observation memory vs. OKF knowledge

Facts use the same frontmatter keys (type, title, description, tags) OKF’s indexer reads.

Per-turn retrieval

Every prompt, not just session start, can pull relevant memory, briefing updates and docs context in front of it. Which harnesses get this, and how:
  • Claude Code calls it from the global user-prompt-submit-hook, registered once in your user-global ~/.claude/settings.json. It fires for every Claude Code session on the machine, in any cwd, a workspace or a project root.
  • Codex calls it from the app-server host, before each turn the host mediates: dashboard messages, pan tell, and pane-typed lines. The result is wrapped in <overdeck-turn-context> and prepended to the prompt; the chat timeline, titles, search and enrichment all strip that block back out, so you see only your own text. The native Codex terminal companion and codex.transport: tui do not call it.
  • Pi calls it for issue-linked conversations and work agents.
A conversation’s identity comes from the workspace row that owns it: its own workspace_id, else the project’s main workspace for a project-root conversation. Dashboard boot creates any missing main workspace row for a registered project, so older projects (imported before workspaces existed) get identity too. Every call (hit, miss or error) is logged to ~/.overdeck/memory/<project>/<workspace>/rag-runs/<date>.jsonl; see Reading RAG decision logs.

Workspace observation memory

Besides curated facts, Overdeck extracts observations from every session automatically. They are stored per workspace, not per issue, under ~/.overdeck/memory/<project>/<workspaceId>/ (observations, status, summaries and logs). A scratch or main workspace with no issue agent still collects memory from the conversations that run in it. Relocating a workspace never moves its memory.

Searching and pinning

--target cannot be combined with --workspace, --issue or --global. A pinned path must resolve to a file inside the project, and it is stored relative to the project root. Always pass --workspace or --project to pin, pins and unpin; without either, pin uses the project overdeck. A project pin lasts as long as the project; a workspace pin is deleted with its workspace.

Reading a workspace’s memory back

status and summary take an issue, --workspace, or neither. With neither, they use the workspace that owns your current directory.
An issue id from a project other than overdeck needs --project <key>. --history is capped at 50, but Overdeck keeps only the three most recent archived statuses, so a larger number returns what is kept. pan memory read reaches only inside the workspace’s own memory home: it refuses absolute paths, ../ and symlinks that point outside, so your session transcripts stay out of reach.

Extraction providers

An LLM call turns each raw session into searchable observations. memory.extraction.provider and memory.extraction.model in ~/.overdeck/config.yaml choose it, or Settings → Memory → Extraction provider. The default is anthropic with claude-haiku-5-5. The environment variables OVERDECK_MEMORY_PROVIDER and OVERDECK_MEMORY_MODEL override the config, but setting only one does not merge with it: the unset variable does not fall back to the YAML provider or model, so (for example) setting only OVERDECK_MEMORY_MODEL resets the provider to anthropic and drops the configured fallback chain. Set both variables together when overriding. Query expansion, which turns a prompt into a few search terms, uses the same provider and fallback but skips any provider that is too slow for prompt time.
  • anthropic needs ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in the environment of both the dashboard service and agent sessions, because hooks that call memory run inside the agent’s own process. A Claude subscription login does not authenticate it: the Anthropic SDK reads only API keys and auth tokens from the environment.
  • claude-cli (Claude Code (subscription) in Settings) is for a host with only a Claude subscription login. It runs claude -p with the Claude Code login of the user that runs the dashboard, so run claude as that user and complete /login once. It starts a process per call, so it is a background provider: query expansion never calls it, and memory.worker_concurrency (default 4) limits how many calls run at once.
  • cliproxy routes through the CLIProxy sidecar and is fast enough for query expansion.
memory.extraction.fallback_chain names fallback providers, but only its first entry is tried. Settings shows it as one Fallback provider. Each call, including the notional cost of a claude-cli call, counts toward memory.extraction.per_day_cost_cap_usd (default 5, in US dollars per day, tracked separately for each issue or scratch/main workspace rather than summed across a project; 0 disables the cap). Applying the Anthropic model preset sets the provider back to anthropic and the model to claude-haiku-5-5.

Extraction health

pan memory doctor --project <key> prints memory health for that project’s issue workspaces, one line per issue. A line with failures ends with failures=<reason>:<count>, followed by an indented cause: line once a failure has a detail. pan doctor shows one Memory extraction row for the newest success or failure across all memory. Both read the health.json evidence that extraction writes; they never test your own shell’s environment, so they catch a missing key even when your shell has one set. Provider and parse failures use these reasons: timeout and provider-non-interactive appear in the logs below, not in health.json. health.json also records failures in later pipeline stages, such as write-failed or rollup-failed.

Reading RAG decision logs

Every prompt-time memory attempt, hit or miss, is logged to ~/.overdeck/memory/<project>/<workspaceId>/rag-runs/<date>.jsonl, one JSON object per line. Two line types appear:
  • query-expansion: one per expansion attempt, with outcome (expanded, cache-hit or expansion-failed), the expanded query and expandedTerms, and reason (one of the reasons above, or null on success). No line is written while query expansion is turned off.
  • rag-decision: one per injection attempt: whether anything was injected, and why not.
An annotated rag-decision line, trimmed to the fields that explain a decision:
This example is a failed expansion (expansion.status: "fallback") that still injected memory (hitCounts.observations: 2). When expansion fails, prompt-time retrieval searches a keyword query built from the prompt (stopwords and short words removed) and matches any of its words, so it still finds observations that share words with the prompt. reason depends on outcome:

Previewing

The dashboard’s Context page preview shows the same Project / Operator / Machine memory sections the launch composition injects, for the project the previewed layer belongs to. The preview places memory after the layers rather than before the workspace section; it is a source-labelled audit view, not a byte-identical copy of what a launch sends.

Several machines

Each store travels a different way:
  • Project facts travel through the project repository. Commit a project fact, push it, and a normal git pull of the primary checkout on another machine brings it into that machine’s next sessions.
  • Operator facts travel through your sync remote, once you set it up (next section).
  • Machine facts never travel.
Because the project and operator stores reach other machines, a fact in either can never hold a path into a home directory: it would be true only on the machine that wrote it. pan memory add/edit refuse such text with the exact match and a fix: rewrite it with ~ or a relative path, or keep it on this machine only with --machine. pan done refuses to finish an issue with an uncommitted fact still sitting in the working tree; commit it like any other change before signaling completion.

Syncing operator memory

The operator store becomes a plain git clone of a private repository you own. Create an empty private repository (Overdeck never creates it and never checks that it is private), then run the same command on each machine:
On the first machine, setup pushes your existing operator facts. On every later machine, it pulls them and merges in that machine’s own facts. Before the first commit, setup moves any operator fact that contains a home-directory path into the machine store and prints moved <id> to the machine store. If the remote cannot be reached, setup changes nothing on disk. Credentials come from your own git setup (an SSH key or a credential helper); a token inside an HTTPS URL is never printed. After setup, four things sync the store, and a launch never does:
  1. pan memory sync, run by hand.
  2. pan sync, before its --if-changed shortcut (skipped under --dry-run and --backup-only).
  3. The dashboard, 60 seconds after it starts and then every 15 minutes.
  4. pan memory add|edit|retire --user, once after each write.
Each sync commits local changes, fetches, merges origin/main, and pushes. When two machines changed the same fact, the remote version keeps the id and your version is kept as a new fact <id>-conflict-<machine> with review: [sync-conflict], so it is never injected. Both machines see both versions. Resolve it with:
To keep a conflict copy as its own fact instead of retiring it, clear its review flag with pan memory edit <id> --clear-review (add --user for the operator store), where <id> is the copy’s id. An edit always beats a deletion. A changed fact whose text trips the secret scanner or contains a home-directory path is held back: it stays on this machine, uncommitted, and every sync reports it. pan memory sync --status shows the remote, the last commit, ahead/behind counts as of the last fetch, uncommitted changes, and conflict copies, without touching the network. To move an older home-path operator fact by hand: