2.5 KiB
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
- 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.
- 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.
- 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).
- 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.
- 05-handoff.md — Where we are, what's decided, what's open, and the first concrete actions for the next session.
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, organized by namespaced nested tags (tool/, client/,
domain/, convention/, scope/) rather than folders, and indexed by a small Ruby +
Sequel + SQLite tag index exposed through a CLI. 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 indexes are disposable and rebuilt per machine. A meaning-based
search layer over the vault (QMD) is designed-in but deferred until structured tagging
proves insufficient. The whole thing ships as a global Claude Code plugin with skills so
every project knows how to use it.
Last updated: 2026-06-03