Docmancer's local memory loop is built around memory atoms, small self-contained, source-attributed facts, decisions, rules, preferences, and workflows. Harvested atoms and Docmancer-owned atoms share one search index, but their durable sources remain distinct so you can inspect and remove knowledge without rewriting another tool's files. Interactive recall applies a benchmark-calibrated relevance floor so a weak nearest neighbour is not presented as evidence.
Add a memory atom
docmancer memory add "Production deploys run on Railway" \
--type decision \
--scope project \
--project "$PWD" \
--tag deployment
Scopes are global, project, and team. Use global for cross-project preferences, project for repository-specific knowledge, and team only for a reviewed item that belongs in Git. Secrets are detected and redacted before the Markdown record is persisted.
If another sync holds the index lock, the command still saves the durable record and tells you to run docmancer memory sync later. The write is not lost.
List and inspect
docmancer memory list
docmancer memory list --scope project --project "$PWD" --json
docmancer memory show <record-or-atom-id>
Each editable memory atom has a stable record_id. Its indexed content version has a content-addressed atom_id, which can change when you edit the Markdown body. show includes type, scope, origin, tags, source path, and merge provenance.
Forget safely
Always preview first:
docmancer memory forget <id> --dry-run
docmancer memory forget <id> --yes
For a Docmancer-owned memory atom, forgetting removes the Markdown content and leaves a content-free tombstone. For a harvested atom, Docmancer keeps the Claude Code, Codex, Cursor, or rules file untouched and stores a local suppression record. Sync applies tombstones before merging, so unchanged forgotten atoms do not return.
Where the files live
| Data | Location | Meaning |
|---|---|---|
| Search index | ~/.docmancer/memory.db plus co-located sqlite-vec state | Rebuildable lexical and dense index |
| Personal memory atoms | ~/.docmancer/memories/*.md | Editable YAML-frontmatter Markdown |
| Team memory atoms | <repo>/.docmancer/memory/*.md | Reviewable Git files |
| Tombstones | ~/.docmancer/memory-tombstones.json | IDs, hashes, scope, and time, never deleted text |
| Atom cache | Beside the memory database | Incremental extraction cache |
| Hook cache | Under ~/.docmancer/ | Bounded recall dedupe state, not transcripts |
docmancer memory clear deletes the rebuildable index. It deliberately does not delete durable memory atoms or tombstones.
Local MCP management
The packaged stdio MCP exposes docmancer_memory_add, docmancer_memory_list, docmancer_memory_show, docmancer_memory_forget, and docmancer_memory_promote. Call forget or promote once with confirm=false to inspect the preview, then set confirm=true only after approval. Promotion derives its destination from a validated project_path; callers cannot provide arbitrary output paths.
Evaluate recall
docmancer memory eval --dataset tests/fixtures/memory-eval-sanitized-real.jsonl --gate
docmancer memory eval --dataset questions.jsonl --format json
The report includes top-one correctness, Hit@3, Hit@5, MRR, failed cases, and latency p50/p95. The checked twenty-case corpus uses sanitised question shapes from Claude Code, Codex, and Cursor workflows. --gate requires at least 85 percent top-one correctness, 95 percent Hit@3, and zero failures for scope isolation, forgotten memory, and current-versus-obsolete facts. A JSONL dataset can include kind: memory corpus rows for a self-contained regression or query the current local index when no corpus rows are present.
Memory query and recall hooks share a normalized 0.05 minimum score selected with this corpus. docmancer memory query "<question>" --min-score 0 is available for retrieval diagnostics, but zero-floor output should not be treated as trusted recall.
Audit corpus health
docmancer memory audit
docmancer memory audit --json --fail-on-findings
Audit is local and read-only. It masks likely secrets found before redaction, compares live sources with the last sync, and flags exact cross-source duplicates, oversized sources, and large sources that produce no usable atoms. Human output shows the most actionable findings; JSON includes the complete report.