diff --git a/CLAUDE.md b/CLAUDE.md index c35fc89..d340fc8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,13 +61,13 @@ 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. +**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 (including the `memory-project` skill, previously TODO under Step 6/Part D). 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) +- Hooks: `hooks/` — session-start.sh, session-context.sh (project graph path only), post-tool-use-write.sh, session-end.sh +- Skills: `skills/` — memory-vault, memory-write, memory-reorganize, memory-project - Config: `config.yaml` — vault path, Ollama model (qwen25-coder-7b-16k), env vars - Hook wiring: `~/.claude/settings.json` diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 904a72c..2c0c2e8 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -1,6 +1,6 @@ # Memory Plugin — User Guide -_Last updated: 2026-06-05_ +_Last updated: 2026-06-08_ --- @@ -16,14 +16,11 @@ Every Claude Code session, three hooks fire without any action on your part: **What Claude sees at the start of every session:** -- Vault graph map: top 50 lines of `~/Documents/SecondBrain/graphify-out/GRAPH_REPORT.md` - (graph summary + community hub list) -- Conventions: result of `graphify query "convention"` against the vault -- Journal: path to today's journal file -- Project graph: path to `/graphify-out/graph.json` if it exists (path only — - use `memory-query` to actually query it) +- Project graph: path to `/graphify-out/graph.json` if one exists in the current + project root (path only — use `memory-project` to actually query it) -Claude does not need to be told about your vault or conventions — they are already in context. +The session-context hook no longer injects vault graph map, conventions, or a journal pointer. +Use `memory-vault` to query cross-project knowledge on demand. --- @@ -88,16 +85,30 @@ or onboarding a new team member who needs current structure. ## 4. Using the skills -**`memory-query` — query vault or project graph** +**`memory-vault` — query cross-project knowledge from the vault** ``` -/memory-query what are the conventions for naming hooks? -/memory-query --graph /path/to/project/graphify-out/graph.json how is auth structured? +/memory-vault what are the conventions for naming hooks? +/memory-vault how does the auth pattern work across projects? ``` -Use `memory-query` any time you want Claude to explicitly search memory rather than relying -on what was injected at session start. Required for project graph queries — the session start -injection gives Claude the path but not the content. +Use `memory-vault` any time you want Claude to explicitly search the Obsidian vault rather +than relying on what was injected at session start. Good for conventions, tool behavior, +decisions, and any evergreen knowledge that spans projects. + +**`memory-project` — per-project graph lifecycle (onboard, update, remove, query)** + +``` +/memory-project query how is auth structured? +/memory-project onboard +/memory-project update +/memory-project remove +``` + +Use `memory-project` to query the current project's graph or to manage its lifecycle. +Required for project graph queries — the session start injection gives Claude the path but +not the content. `onboard` runs the full extract + cluster sequence; `update` does an +incremental refresh; `remove` drops the graph and cleans up `.gitignore`. **`memory-write` — write evergreen knowledge to vault** @@ -180,7 +191,7 @@ tag-based clustering in Graphify, it will not work; use hub notes and explicit w **Project graph injection is path-only.** At session start, Claude receives the path to `/graphify-out/graph.json` — not -the content. To actually query the project graph, invoke `memory-query` with `--graph `. +the content. To actually query the project graph, invoke `memory-project query `. Claude will not automatically read the project graph without being asked. **memsearch (episodic memory) is not built yet.** diff --git a/docs/memory-system/04-build-plan.md b/docs/memory-system/04-build-plan.md index 03effa7..10c63ea 100644 --- a/docs/memory-system/04-build-plan.md +++ b/docs/memory-system/04-build-plan.md @@ -174,8 +174,8 @@ Hooks now call Graphify instead of the Ruby CLI. nodes — a periodic `--force` rebuild (e.g. weekly, or triggered by SessionStart stale check) is needed to clear ghost nodes. - **SessionStart**: reconcile (check vault graph mtime vs last rebuild; trigger `--force` if - stale threshold exceeded) + inject context (query MCP server for god nodes + inject - `convention/*` note summaries + journal pointer). + stale threshold exceeded) + inject context (emits project graph path if a + `graphify-out/graph.json` exists at the project root; vault context injection was removed). - **SessionEnd**: append daily journal note with pointers to vault notes touched. **Stale-node mitigation strategy:** track last `--force` rebuild time in a stamp file @@ -200,8 +200,8 @@ older than N days (7 is a reasonable starting point). - 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). +4 skills (`memory-vault`, `memory-write`, `memory-reorganize`, `memory-project`). Plugin enabled in +`~/.claude/settings.json`. ### Step 7 — (SKIPPED) QMD semantic layer Covered by Graphify. The knowledge-graph approach provides structured semantic retrieval @@ -239,9 +239,10 @@ project-ephemeral state (that's the episodic layer / project files). Concretely: - Add `--budget N` to cap answer size (default ~2000 tokens); `--dfs --budget N` for bounded traversal - Add `--graph ` to query a specific project's `graph.json` instead of the vault graph -**At session start**: god-node summary (injected by hook from `GRAPH_REPORT.md`) gives the -architecture spine — what are the highest-connectivity concepts in the vault. The AI then -queries specific nodes on demand rather than reading everything. +**At session start**: the session-context.sh hook emits the project graph path (pointing at +`/graphify-out/graph.json`) if one exists — vault context injection (god-node +summary, convention summaries, journal pointer) was removed. The AI queries the vault or +project graph on demand rather than having it injected. **On demand, during a task**: run `graphify query` when the task touches a tool/client/domain. The graph returns relevant node clusters; the AI opens only the vault notes whose `summary` @@ -262,7 +263,7 @@ SEMrush concept, regardless of which client project they came from. Graph edges | **Read / query** | AI needs knowledge | AI runs `graphify query` / `graphify explain` via Bash (no hook; on-demand) | | **Update** | AI/user edits a note | AI edit → **PostToolUse** → `graphify update --file`; user edit → **SessionStart** reconcile | | **Delete / rename** | note removed/renamed | `graphify update --file` prunes AI-deleted paths; **SessionStart** triggers `--force` rebuild if stale (catches manual deletes) | -| **Inject** | new session starts | **SessionStart** hook: god-node summary + `convention/*` summaries + journal pointer | +| **Inject** | new session starts | **SessionStart** hook: emits project graph path (vault context injection removed) | | **Journal** | session ends | **SessionEnd** hook appends a dated journal note with pointers | | **Reorganize** | periodic, user-invoked | `reorganize memory` in **plan mode**: dedupe, merge, split, re-scope, then `graphify --force` to rebuild clean graph — human approves | | **Stale graph rebuild** | SessionStart stale check | If rebuild stamp > N days old: `graphify --force` on vault; resets stamp | @@ -270,7 +271,7 @@ SEMrush concept, regardless of which client project they came from. Graph edges Hooks are thin shell wrappers; the logic lives in Graphify. **Hooks summary:** -- **SessionStart** — stale check + `--force` if needed, then inject (god nodes + conventions + journal pointer). +- **SessionStart** — stale check + `--force` if needed, then inject project graph path (vault context injection was removed; session-context.sh now only emits the project graph path). - **PostToolUse** (on `Write`/`Edit` of vault `.md`) — `graphify update --file`. - **SessionEnd** — append daily journal note. - (memsearch brings its own hooks for the episodic layer.) @@ -294,14 +295,14 @@ Graphify config. - **Skills** (these carry the *know-how* to the model): - `memory-write` — when to record evergreen knowledge, the frontmatter contract (summary required, scope rule), "vault not repo." - - `memory-query` — how/when to use `graphify query` vs memsearch; god-node discipline; + - `memory-vault` — how/when to use `graphify query` vs memsearch; god-node discipline; `--budget`/`--dfs` usage; cross-client lookups via `--graph`; progressive-disclosure 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: + - `memory-project` **DONE (2026-06-08)** — 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`) + - **Query**: `graphify query ... --graph ` for project-context queries (wraps `memory-vault`) - **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 diff --git a/docs/memory-system/05-implementation-process.md b/docs/memory-system/05-implementation-process.md index 1ca4581..9d83b33 100644 --- a/docs/memory-system/05-implementation-process.md +++ b/docs/memory-system/05-implementation-process.md @@ -338,7 +338,7 @@ Graphify config. `--graph /graphify-out/graph.json`. - **Skills** (carry the know-how to the model): - `memory-write` — when to record evergreen knowledge, frontmatter contract, scope rule, vault not repo. - - `memory-query` — `graphify query` vs memsearch; god-node discipline; `--budget`/`--dfs`; cross-client lookups; progressive disclosure via `summary`. + - `memory-vault` — `graphify query` vs memsearch; god-node discipline; `--budget`/`--dfs`; cross-client lookups; progressive disclosure via `summary`. - `memory-reorganize` — plan-mode consolidation/promotion procedure; when to trigger `--force` rebuild; human-approval guardrails. - **Env vars** baked in: `OLLAMA_FLASH_ATTENTION=1`, `GRAPHIFY_OLLAMA_KEEP_ALIVE=5`, `OLLAMA_BASE_URL=http://127.0.0.1:11434/v1`, `OLLAMA_API_KEY=`. Note: