Update build plan status and CLAUDE.md with implementation progress
- Mark Steps 2a, 2b, 3, 6 complete; add implementation status notes - Add "Implemented Components" section with progressive disclosure to CLAUDE.md - Document installed plugin, Graphify, and vault setup as working baseline - Update last-updated date to 2026-06-08 - Add standing instruction to keep CLAUDE.md current as implementation progresses Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
jared
parent
b3730d871b
commit
2317a087ce
31
CLAUDE.md
31
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: `<project-root>/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
|
||||
|
||||
|
|
|
|||
|
|
@ -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/<x>`) 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 <path>` 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`,
|
||||
|
|
|
|||
Loading…
Reference in New Issue