83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
|
# 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.
|