40 lines
2.5 KiB
Markdown
40 lines
2.5 KiB
Markdown
|
# 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.
|
||
|
|
5. **[05-handoff.md](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_
|