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:
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,planHomeis 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 runpan 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.
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:## 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
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:
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: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).
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.
- Links: supersession problems: an id that names no fact, a link recorded on only one side, a
status: supersededwithoutsuperseded_by(or the reverse), a supersession cycle, and an active fact whose description says it is superseded, with thepan 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.
--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.
Search
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 andcodex.transport: tuido not call it. - Pi calls it for issue-linked conversations and work agents.
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.
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.
anthropicneedsANTHROPIC_API_KEYorANTHROPIC_AUTH_TOKENin 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 runsclaude -pwith the Claude Code login of the user that runs the dashboard, so runclaudeas that user and complete/loginonce. It starts a process per call, so it is a background provider: query expansion never calls it, andmemory.worker_concurrency(default 4) limits how many calls run at once.cliproxyroutes 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, withoutcome(expanded,cache-hitorexpansion-failed), the expandedqueryandexpandedTerms, andreason(one of the reasons above, ornullon success). No line is written while query expansion is turned off.rag-decision: one per injection attempt: whether anything was injected, and why not.
rag-decision line, trimmed to the fields that explain a decision:
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 pullof 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.
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: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:
pan memory sync, run by hand.pan sync, before its--if-changedshortcut (skipped under--dry-runand--backup-only).- The dashboard, 60 seconds after it starts and then every 15 minutes.
pan memory add|edit|retire --user, once after each write.
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:
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: