--- name: pan-memory description: "pan memory — search and inspect Overdeck memory observations, status, reset markers, summaries, and health" triggers: - pan memory - memory search - memory status - memory --target allowed-tools: - Bash - Read --- # Pan Memory Use `pan memory` to inspect the durable memory substrate for a project or issue. ## Commands ```bash pan memory search [--project ] [--workspace ] [--issue ] [--tag ] [--sibling] [--global] [--target [path]] [--include-archived] [--limit ] [--json] pan memory status [issue] [--project ] [--workspace ] [--history ] [--json] pan memory timeline [--workspace ] [--days ] [--limit ] [--json] pan memory read [--workspace ] [--from ] [--lines ] pan memory reset --reason [--project ] [--from ] [--json] pan memory summary [issue] [--project ] [--workspace ] [--date ] [--json] pan memory doctor [--project ] [--json] pan memory backfill [--workspace ] [--project ] [--dry-run] [--json] pan memory pin [--project | --workspace ] [--json] pan memory unpin [--project | --workspace ] [--json] pan memory pins [--project | --workspace ] [--json] pan memory config [--json] pan memory show [--project | --user | --machine | --here] pan memory list [--type ] [--query ] [--review] [--project | --user | --machine | --here] [--json] pan memory add --type --description [--title ] [--body | --body-file ] [--tags ] [--project | --user | --machine] [--json] pan memory edit [--type ] [--title ] [--description ] [--body | --body-file ] [--tags ] [--clear-review] [--project | --user | --machine] [--json] pan memory retire [--project | --user | --machine] [--json] pan memory sync [--setup ] [--status] [--json] ``` ## Notes - `search --sibling --issue ` searches same-project sibling issues instead of the selected issue. - `search --global` merges results across every registered project instead of just the selected/default one. - `search --workspace` accepts either a workspace id or a workspace name; a name matching more than one workspace across projects errors instead of guessing. - `search --target [path]` (Subspace `target-search` parity) finds every non-archived workspace whose `path` targets a directory — bare `--target` defaults to the current working directory. Mutually exclusive with `--workspace`/`--issue`/`--global`. Fans out per matched workspace (which may span several projects) and merges by rank score, same as `--global`'s per-project merge. When no workspace targets the directory, prints a friendly "No workspaces target ``." note and exits 0. - `search` (human output only) prints matching curated facts first, under `Project memory:`/`Operator memory:`/`Machine memory:` (PAN-3957, PAN-4578, at most 5 each), before the observation hits below them. `--json` is unchanged — still the observation array only. - `status` and `summary` address a workspace three ways, in precedence order: `--workspace `, an issue positional, then the workspace that owns the current directory. With none of the three resolvable the command exits non-zero and names all three modes. A workspace with no issue (main/scratch) is titled by its workspace name in `summary` output. - `status --history ` prints the current status first, then up to N archived statuses newest-first with their archive timestamp, phase, and headline. N is capped at 50; the rollup writer prunes the on-disk archive to its three most recent entries, so N above 3 returns whatever is still retained. `--history` with `--json` emits `{current, history}` where each history entry is `{archivedAt, path, status}`. - `timeline` prints one row per observation — timestamp, the action status or summary, and the files touched — oldest first, for the workspace named by `--workspace` or the one owning the current directory. `--days` counts today as day 1 and defaults to 7; `--limit` caps the row count at the 50 most recent by default; `--json` emits the observation rows. - `read` prints a file from the workspace's memory home; `` is relative to that home and `--from`/`--lines` slice it by 1-based line number. It refuses, with a non-zero exit, any absolute path, any `../` traversal, and any symlink whose real target is outside the home — so Claude Code JSONL session files under `~/.claude` are unreachable by construction. - `reset` creates a reset marker; it does not delete historical memory records. - `doctor` exits non-zero when an active agent has no successful extraction in the last hour. - `backfill` reads historical Claude Code JSONL transcripts under `~/.claude/projects/` and extracts observations for sessions whose first-message cwd maps to a registered workspace; unmatched sessions are skipped. Read-only on the JSONL files — `--dry-run` reports matches without extracting or writing anything. - `pin`/`unpin`/`pins` manage docs injected under the knowledge budget at prompt time. `--workspace` overrides `--project`; paths are stored project-relative regardless of scope. - `show`/`list` read curated memory facts (PAN-3957) — short, human-reviewable markdown files with frontmatter, committed in the repo and distinct from the observation substrate above. `--project ` always reads that project's primary checkout; with neither `--project` nor `--user`, `show`/`list` default to the primary checkout too (the store the launch-time index was rendered from) — pass `--here` to read the cwd checkout's own store instead (useful inside a workspace before its branch merges). `list` defaults to active facts only; `--review` shows only facts carrying a review marker, and `list` exits non-zero when any fact file fails to parse, printing a `Problems:` block. - `add`/`edit`/`retire` write curated facts into the checkout that owns the cwd (or `--project `'s primary checkout, or `--user` for the operator store, or `--machine` for the machine store); they never accept `--here` and never commit — each prints the `git add`/`git rm` + commit hint to run yourself. `add --type user` without `--user` or `--machine` is refused (user facts belong in the operator store). The operator store (`--user`) travels with you across machines and refuses home-directory paths; the machine store (`--machine`, `~/.overdeck/context/machine-memory/`) is this machine only and accepts them. A fact whose text contains an absolute home-directory path is refused in the project and operator stores, and secret-like text is refused everywhere. `edit` requires at least one field flag and always bumps `updated`; `--clear-review` removes a review marker, reactivating the fact in the launch index. - `sync` (PAN-4578) syncs the operator store with a private git repository you own. `--setup ` turns it on once per machine (it moves home-path facts to the machine store first); after that `pan sync`, the dashboard, and every `--user` write sync it too, and `--status` reports its state without the network. When two machines edit the same fact, the remote version keeps the id and yours is kept as a review-marked `-conflict-` fact to resolve with `edit --user` and `retire --user`. A changed fact that contains secret-like text or a home-directory path is held back: it stays on this machine, uncommitted, and every sync reports it.