# Memory System — Documentation Set

A personal, cross-project memory system for Claude Code: lightweight, fast, tag-organized,
self-evolving, local-fast with lazy remote sync. Built for a multi-client freelancer who
wants the AI to learn things once and reuse them everywhere, without bloating project repos.

## Read in this order

1. **[01-video-synthesis.md](01-video-synthesis.md)** — Synthesis of the "6 Levels of Claude
   Code Memory" video. What each level/tool is, where memory lives, how it's retrieved, and
   the author's recommendations. Background reading; the source of many ideas below.
2. **[02-system-design.md](02-system-design.md)** — The architecture we settled on. Three
   layers (episodic / knowledge / deferred-semantic), the knowledge-layer internals, data
   model, hooks, sync, and guardrails. **Start here if you only read one.**
3. **[03-architecture-decisions.md](03-architecture-decisions.md)** — ADR log. Every decision
   and *why*, including what we rejected and why (MemPalace, OpenBrain/Mem0, Postgres,
   Recall/LightRAG) and what we deferred (semantic search over the vault).
4. **[04-build-plan.md](04-build-plan.md)** — How a human builds this, step by step. The
   scripts, the hooks, the CRUD lifecycle, the AI's write/query conventions, and the
   Claude Code plugin + skills that package it for global install.

## One-paragraph summary

Two complementary memory types kept as **separate systems**: **episodic** ("what happened,
when") handled by **memsearch** (Milvus Lite, embedded, auto-captured session/journal notes),
and **semantic/knowledge** ("how do we…") handled by a **flat Obsidian markdown vault** that
is the single source of truth. Every note carries **`summary` + namespaced tags** (`tool/`,
`client/`, `domain/`, `convention/`, `scope/`) as first-class metadata — the human-written
router hint and the cross-cutting filters that organize the vault without folders. The vault is
made queryable by a **Graphify knowledge graph** (local Ollama SLM extracts entities/relations
from the notes; free tree-sitter AST builds a code graph per project). Retrieval is
**hook-injected and on-demand** so project repos stay thin. Freshness is **lazy** (a write-time
hook plus a session-start reconcile — no daemon, no cron). Everything is markdown-as-truth and
syncs to a VPS via **git/Syncthing**; the graphs are disposable and rebuilt per machine. The
whole thing ships as a **global Claude Code plugin with skills** so every project knows how to
use it.

_Last updated: 2026-06-04 · knowledge layer = Graphify knowledge graph (supersedes the earlier
Ruby tag-index CLI; metadata frontmatter retained)_