Document memory-project skill completion and vault/project query refactor
Complete the memory-project skill implementation. Rename memory-query to memory-vault, split project graph queries into memory-project skill, mark memory-project DONE in build plan, and clarify session-context.sh scope (now project graph path only — vault injection removed). Update user guide with examples of both vault and project graph query workflows.
This commit is contained in:
jared
parent
ece3469889
commit
5834036370
|
|
@ -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`
|
||||
|
||||
|
|
|
|||
|
|
@ -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 `<project>/graphify-out/graph.json` if it exists (path only —
|
||||
use `memory-query` to actually query it)
|
||||
- Project graph: path to `<project>/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 `<project>/graphify-out/graph.json` — not
|
||||
the content. To actually query the project graph, invoke `memory-query` with `--graph <path>`.
|
||||
the content. To actually query the project graph, invoke `memory-project query <question>`.
|
||||
Claude will not automatically read the project graph without being asked.
|
||||
|
||||
**memsearch (episodic memory) is not built yet.**
|
||||
|
|
|
|||
|
|
@ -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 <path>` 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
|
||||
`<project-root>/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 <path>` for project-context queries (wraps `memory-query`)
|
||||
- **Query**: `graphify query ... --graph <path>` 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
|
||||
|
|
|
|||
|
|
@ -338,7 +338,7 @@ Graphify config.
|
|||
`--graph <project-root>/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=<any-non-empty>`. Note:
|
||||
|
|
|
|||
Loading…
Reference in New Issue