diff --git a/CLAUDE.md b/CLAUDE.md index 1b0d1f9..c35fc89 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,14 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What this repository is -`cc-os` is a **documentation- and design-only repository** — there is no application code, -build, lint, or test step yet. It captures the design of a **personal, cross-project memory -system for Claude Code** (for a multi-client freelancer) plus the research that informs it. -Implementation has **not started**; the deliverables here are markdown specs, ADRs, and a -build outline that a future session turns into a real implementation. +`cc-os` is a **design + implementation repository** — it captures the design of a **personal, +cross-project memory system for Claude Code** (for a multi-client freelancer) plus the research +that informs it. The global memory plugin is now partially implemented; markdown specs, ADRs, +and the build plan remain the source of truth for what is being built and what remains. -Everything is markdown-as-truth. When asked to "build," the next step is to convert the -existing build outline into a staged implementation plan, not to start coding ad hoc. +Everything is markdown-as-truth. When asked to "build," work from the staged tasks in +`docs/memory-system/04-build-plan.md`, not ad hoc. ## Directory layout @@ -62,6 +61,23 @@ to those two and fix the stale doc. **Empirical finding locked (2026-06-05):** Graphify is a structure extractor, not a topic clusterer — no emergent hub nodes appear even at `--mode deep`; hub notes + wikilinks must be author-provided during migration (not deferred). Migration scaffolding is now a first-class deliverable. Open question: do facet tags create graph edges? (ADR-014; findings: `docs/memory-system/07-graph-connectivity-findings.md`). +**Implementation status (2026-06-08):** The global Claude Code plugin is live (`~/.claude/plugins/memory/`). Steps 2a, 2b, 3, and 6 of the build plan are complete. Steps 1 (vault conventions), 4 (memsearch), and 5 (sync) remain. See `docs/memory-system/04-build-plan.md` for full step status. + +## Implemented Components + +**Global memory plugin** — `~/.claude/plugins/memory/` +- Hooks: `hooks/` — session-start.sh, session-context.sh, post-tool-use-write.sh, session-end.sh +- Skills: `skills/` — memory-query, memory-write, memory-reorganize (`memory-project-graph` is TODO) +- Config: `config.yaml` — vault path, Ollama model (qwen25-coder-7b-16k), env vars +- Hook wiring: `~/.claude/settings.json` + +**Graphify** — v0.8.31 at `/home/jared/.local/bin/graphify` +- Vault graph: `~/Documents/SecondBrain/graphify-out/` — disposable, rebuilt by SessionStart hook +- Project graph: `/graphify-out/` — same pattern; gitignore it in each project repo +- Vault conventions: `~/Documents/SecondBrain/CONVENTIONS.md` — frontmatter contract + tag taxonomy + +**Not yet implemented:** vault conventions migration (Step 1), memsearch episodic layer (Step 4), VPS sync (Step 5) + ## OpenSpec workflow Changes are managed spec-driven via OpenSpec. Use the matching skills rather than editing spec @@ -85,6 +101,7 @@ project context for OpenSpec artifacts comes from `docs/` and this file. - **Decisions live in ADRs.** Don't silently reverse a locked decision; add or amend an ADR in `03-architecture-decisions.md` with the reasoning. - The package on PyPI is `graphifyy` (double-y) but the command is `graphify`. +- **Keep this file current:** When a build step completes, (a) mark it done in `docs/memory-system/04-build-plan.md`, (b) add or update a component pointer in the Implemented Components section above, and (c) update the current design paragraph if the design changed. This file is the AI's orientation entry point — accuracy matters more than brevity. ## Session Orchestration diff --git a/docs/memory-system/04-build-plan.md b/docs/memory-system/04-build-plan.md index 1caff3e..03effa7 100644 --- a/docs/memory-system/04-build-plan.md +++ b/docs/memory-system/04-build-plan.md @@ -1,6 +1,6 @@ # Build Plan -_Last updated: 2026-06-04_ +_Last updated: 2026-06-08_ How a human builds this system, step by step, and answers to the operational questions: which scripts and hooks, how the AI knows when to write and what conventions to follow, how and @@ -37,21 +37,28 @@ plugin that packages it. `summary` (one-line, author-written — this is the human-readable router hint Graphify does not generate) and `scope` (`scope/global` or `scope/project`). Tags are now supplementary, not the primary query mechanism. + **Open question (2026-06-08):** The vault currently has a `vault-conventions.md` file, not + `CONVENTIONS.md`. Whether to rename/align, or treat `vault-conventions.md` as the canonical + name, is undecided. Resolve before the migration scaffolding deliverable is finalized. - Seed a few real notes (e.g. `tool/semrush`, `client/`) to use as extraction test cases in Step 2. +**Status: NOT STARTED** + ### Step 2 — Graphify + Ollama setup (the knowledge graph layer) This replaces the Ruby tag-index CLI. Graphify builds a knowledge graph over vault docs via a local SLM, and a free code graph over project files via AST. -#### 2a — Install Graphify +#### 2a — Install Graphify **DONE (2026-06-08)** ``` pip install graphify # or follow current install docs ``` Verify: `graphify --version` -#### 2b — Configure Ollama for extraction +**Status:** `graphify` v0.8.31 installed at `/home/jared/.local/bin/graphify`. + +#### 2b — Configure Ollama for extraction **DONE (2026-06-08)** The 2024 approach (Modelfile with `PARAMETER num_ctx`) still works but the preferred programmatic method is now per-request via the API (Graphify supports this via `GRAPHIFY_OLLAMA_NUM_CTX`): @@ -65,6 +72,11 @@ GRAPHIFY_OLLAMA_NUM_CTX=8192 # 8K is sufficient for vault notes (200-2000 w To verify context is being used: `ollama ps` shows allocated context after first call. +**Status:** All env vars set in `~/.claude/plugins/memory/config.yaml`: +`OLLAMA_FLASH_ATTENTION=1`, `GRAPHIFY_OLLAMA_NUM_CTX=8192`, `GRAPHIFY_OLLAMA_KEEP_ALIVE=5`. +Model locked to `qwen25-coder-7b-16k` (per ADR and memory note — this is Graphify's default +and the confirmed working extraction model). + Available models (as of 2026-06-03, in order of interest): - `gemma4:e2b` — 7.2 GB, ~2B effective params, 128K native window, fast; **start here** - `qwen3.5:2b` — 2.7 GB, smallest, good fallback if VRAM is constrained @@ -122,6 +134,12 @@ Tune `--token-budget` (semantic chunk size) and `--max-concurrency` based on VRA Review `GRAPH_REPORT.md` — check god nodes make sense (they should be your most-connected tools, clients, and domain concepts). +**Note (2026-06-08):** The `~/Documents/SecondBrain` vault already has a live `graphify-out/` +graph (32 files, built 2026-06-05). The fixture-first approach from ADR-013 may therefore be +superseded — the vault graph exists before Step 1 (conventions/fixtures) is formally complete. +Determine whether to treat the existing vault graph as the fixture baseline or run a clean +fixture-only build once Step 1 is done. This is an open question before 2d can be marked done. + **Full vault migration** (the `~/Documents/SecondBrain` build above run over all notes) is the final step — deferred to after end-to-end validation on the pilot project. Do not bulk-migrate the vault until the system is verified working on the fixture set and pilot project. @@ -141,7 +159,13 @@ subsequent runs; use `--force` when you've deleted files (to clear stale nodes). Store each project's `graphify-out/` alongside the project, or in a configurable cache dir. Keep per-project graphs separate — do not merge client projects into one graph. -### Step 3 — Hooks (maintenance + retrieval) +**Note (2026-06-08):** A `graphify-out/` for the `cc-os` project exists (built 2026-06-05), +but `cc-os` is a docs-only repo, not a pilot project in the ADR-013 sense. A pilot project +with real code has not yet been onboarded. + +**Status: NOT STARTED** (pilot project onboard pending) + +### Step 3 — Hooks (maintenance + retrieval) **DONE (2026-06-08)** Hooks now call Graphify instead of the Ruby CLI. @@ -158,7 +182,7 @@ Hooks now call Graphify instead of the Ruby CLI. (e.g. `~/.cache/graphify/vault-rebuild.stamp`). SessionStart hook triggers `--force` if older than N days (7 is a reasonable starting point). -### Step 4 — Episodic layer (memsearch) +### Step 4 — Episodic layer (memsearch) — NOT STARTED - Install memsearch (`/plugin marketplace add zilliztech/memsearch`, then `plugin install memsearch`), local to start. Verify daily memory files appear after a few conversations. - Decide whether memsearch indexes our session-end journal notes or its own capture (likely its @@ -166,15 +190,19 @@ older than N days (7 is a reasonable starting point). - Graphify does **not** replace memsearch here. Time-anchored semantic queries ("what was I working on last Tuesday?") are better served by vector similarity over session logs. -### Step 5 — Sync +### Step 5 — Sync — NOT STARTED - Pick **git** (versioned, hourly push/pull) or **Syncthing** (continuous, zero-thought) for the vault → VPS. Configure on each machine. - **Do not sync** the Graphify `graphify-out/` directories, Milvus caches, or the Ollama models. Graphs are rebuilt per machine from the vault (the single source of truth). -### Step 6 — Package as a global plugin (Part D) +### Step 6 — Package as a global plugin (Part D) **DONE (2026-06-08)** - Wrap Steps 2–3 into a Claude Code plugin with skills; install at user level. +**Status:** Global plugin installed at `~/.claude/plugins/memory/` with all hook scripts and +3 skills (`memory-query`, `memory-write`, `memory-reorganize`). Plugin enabled in +`~/.claude/settings.json`. `memory-project-graph` skill still TODO (see Part D below). + ### Step 7 — (SKIPPED) QMD semantic layer Covered by Graphify. The knowledge-graph approach provides structured semantic retrieval without vectors. Only revisit if Graphify's graph queries prove insufficient for a use case @@ -247,6 +275,9 @@ Hooks are thin shell wrappers; the logic lives in Graphify. - **SessionEnd** — append daily journal note. - (memsearch brings its own hooks for the episodic layer.) +**Status:** All 4 hooks wired in `~/.claude/settings.json`: SessionStart, UserPromptSubmit +(context injection), PostToolUse (vault writes), SessionEnd (journal). + --- ## Part D — Claude Code plugin with skills (global install) @@ -268,6 +299,11 @@ Graphify config. via summary field. - `memory-reorganize` — the plan-mode consolidation/promotion procedure + guardrails; when to trigger `graphify --force` rebuild. + - **TODO (2026-06-05):** `memory-project-graph` — full lifecycle skill for per-project Graphify graphs: + - **Onboard**: `graphify extract . --backend ollama --model qwen2.5-coder:7b`, then `graphify cluster-only .`, add `graphify-out/` to `.gitignore` + - **Query**: `graphify query ... --graph ` for project-context queries (wraps `memory-query`) + - **Update**: `graphify update .` for incremental updates (no API cost) or `--force` rebuild after structural changes + - **Remove**: delete `graphify-out/` when no longer needed - **Config**: vault path, Graphify output dir, Ollama model name, `num_ctx`, rebuild-stale threshold in days — set once at user level. - **Env vars** set by plugin: `OLLAMA_FLASH_ATTENTION=1`, `GRAPHIFY_OLLAMA_NUM_CTX=8192`,