jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/docs/memory-system/05-handoff.md

4.4 KiB
Raw Blame History

Session Handoff

Written 2026-06-03 at the end of the brainstorming session. For the next session to pick up.

What this is

Designing a personal, cross-project memory system for Claude Code for a multi-client freelancer. We finished brainstorming/architecture and wrote the design + ADRs. No implementation has started. The source material is the transcript at /home/jared/Documents/cc-os/memory-systems-compared060326 (the "6 Levels of Claude Code Memory" video).

Where we are

  • ✅ Synthesized the video (01-video-synthesis.md).
  • ✅ Settled the architecture and got user sign-off (02-system-design.md).
  • ✅ Recorded every decision + rejected/deferred options (03-architecture-decisions.md).
  • ✅ Wrote the build outline + operational answers (04-build-plan.md).
  • ⏳ Next: turn 04-build-plan.md into a real implementation plan and start building.

The design in 30 seconds

Three local, markdown-as-truth, no-Docker layers:

  1. Episodic ("what happened, when") = memsearch (Milvus Lite, off-the-shelf).
  2. Knowledge ("how do we…") = flat Obsidian vault (single source of truth) + a Ruby/Sequel/SQLite tag index with a CLI. Organized by namespaced nested tags (tool/ client/ domain/ convention/ scope/), not folders.
  3. Semantic over the vault = QMD, deferred until structured tagging proves insufficient.

Retrieval is hook-injected + on-demand (projects stay thin). Freshness is lazy (write-time hook + session-start reconcile; no daemon/cron). Vault syncs to a VPS via git/Syncthing; indexes are disposable and rebuilt per machine. Ships as a global Claude Code plugin with skills.

Decisions locked (don't relitigate without reason)

  • Two separate systems for episodic vs knowledge (ADR-001).
  • memsearch for episodic (ADR-002). Flat vault + tags, not folders (ADR-003).
  • SQLite + Sequel (Ruby) CLI tag index; markdown authoritative, cache disposable (ADR-004).
  • Structured-first; semantic (QMD) deferred (ADR-005/006).
  • Lazy freshness: PostToolUse write hook + SessionStart reconcile, no daemon/cron (ADR-007).
  • Sync the vault not the indexes; reject OpenBrain/Mem0/Postgres (ADR-008).
  • Package as a global plugin with skills (ADR-009).
  • Query output = path + summary + matched tags (option C).

Open questions for build time

  1. Vault location — default ~/brain (or similar synced home dir)? Symlink into ~/.claude/memory only if a tool requires it.
  2. Sync mechanism — git (versioned history, hourly) vs Syncthing (continuous, zero-thought).
  3. Convention notes placement — confirmed direction: coding convention/* live as data in the vault (resolved by the SessionStart hook); the memory-system skills live in the plugin (behavior, versioned). Validate when building.
  4. memsearch journal — does memsearch index our SessionEnd journal notes, or only its own auto-capture? Decide how the journal points into the knowledge vault.
  5. Promotion rule — the concrete threshold for project→scope/global promotion (e.g. recurrence count) used by the reorganize step.
  6. CLI ergonomics — command framework (thor vs optparse), output format details, where last_cache_time is stored.

Recommended first actions next session

  1. Re-read 02-system-design.md and 04-build-plan.md.
  2. Invoke the writing-plans skill to convert 04-build-plan.md Part A into a staged implementation plan (Step 2, the Ruby tag-index CLI, is the critical path — build and test it standalone first).
  3. Resolve open questions 1–2 (vault location + sync) before writing code, since they affect paths in the hooks and CLI.
  4. Build Step 2 (CLI) with tests, then Step 3 (hooks), then validate end-to-end on the seeded notes before touching the plugin packaging (Step 6).

Context notes

  • Working dir /home/jared/Documents/cc-os is not a git repo; consider git init if we want history for these docs and the build.
  • User prefers Docker when reasonable — but this design deliberately needs none (all layers are embedded/local). Only full Milvus or QMD-server modes would involve Docker, and we're not using those.
  • User is Ruby-comfortable (chose Ruby + Sequel deliberately).
  • A past ~/Documents/SecondBrain/ attempt (tag DB) was lost track of — the "markdown authoritative, cache disposable & rebuildable" rule (ADR-004) is the explicit fix for that.