memory-graph

---

Implements the Karpathy LLM Knowledge Base pattern. Default LLM memory has two failure modes:

1. RAG-only systems rediscover knowledge from raw documents on every question. Nothing accumulates.
2. Bag-of-facts memory (Settings → Memory, flat MEMORY.md files) has no structure, no cross-references, no notion of contradicting or superseding past entries.

memory-graph builds and maintains a persistent, compounding artifact — a wiki the agent owns and you read, sitting between you and your raw sources. New sources get integrated, not just indexed. Contradictions are flagged. Cross-references are maintained. The knowledge is compiled once and kept current.

✨ Features

• 🧬 Karpathy three-layer architecture — raw/ (immutable sources), wiki/ (LLM-owned interlinked markdown), SCHEMA.md (co-evolved configuration)
• 🗂️ Two vaults — per-project (~/.memory-graph/<sanitized-cwd>/) and global (~/.memory-graph/global/); identical layout; no auto-merge
• 🪜 Co-authored SCHEMA — /graph-init interviews you on scope, source kinds, entity types, workflows, and hard rules, then writes a personalized SCHEMA.md (not a template)
• 🔗 Index-first retrieval — query reads wiki/index.md first, drills into selected pages, never scans the whole vault, never embed-searches; the perf contract is non-negotiable
• 📝 Proactive auto-ingest — files URL/file shares, entity updates, and decision-shaped answers automatically (first-confirm-then-trust per session, [auto] / [manual] log marker for selective rollback)
• 🔍 9-check lint — orphans, broken links, contradictions, stale sources, schema-drift, rule-drift, missing pages, uncited claims, index-drift; stable issue IDs; no auto-apply
• 📦 Archive snapshots — cp -a to a parallel tree outside the vault root (~/.memory-graph-archive/); restore is manual by design
• 🤖 Dual distribution — Claude Code plugin AND PI extension from the same repo, sharing one SKILL methodology and the same vaults on disk

🗄️ Two vaults

~/.memory-graph/
├── global/                              ← one per machine, cross-project knowledge
│   └── {raw, wiki, SCHEMA.md}
└── <sanitized-cwd>/                     ← one per project (cwd with `/` → `-`)
    └── {raw, wiki, SCHEMA.md}

~/.memory-graph-archive/                 ← snapshots, parallel tree outside vault
├── global/<label>-YYYYMMDD/
└── <sanitized-cwd>/<label>-YYYYMMDD/

Inside each vault root:

<vault-root>/
├── raw/          immutable source material — agent reads, never writes
├── wiki/         agent-owned interlinked markdown — you read, agent writes
│   ├── index.md  catalog, one line per page
│   ├── log.md    append-only chronological record
│   ├── entities/
│   ├── concepts/
│   ├── sources/
│   └── synthesis/
└── SCHEMA.md     conventions + workflows, co-authored on init

Slash commands default to the project vault. Pass --global to operate on the global vault. Archives live outside the vault root so ingest / query / lint can't reach them; restore is a manual shell procedure.

🛠️ Operations

Three core operations from Karpathy's pattern, exposed as both Claude Code slash commands and pi commands:

Operation	What it does
ingest	Read a raw source, extract entities/concepts, write a summary page, update affected entity/concept pages, refresh the index, append to the log
query	Read index.md first, drill into the minimum set of relevant pages, synthesize an answer with [[wikilinks]] as citations; optionally file the answer back as a synthesis page
lint	9-check health pass: orphans, broken links, contradictions, stale sources, schema-drift, rule-drift, missing pages, uncited claims, index-drift; report with stable issue IDs; no auto-apply