# 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.