39 lines
4.4 KiB
Markdown
39 lines
4.4 KiB
Markdown
## Why
|
|
|
|
The memory system's knowledge graph (vault + Graphify) and episodic layer (memsearch) are built and validated, but Claude Code has no runtime awareness of them — hooks are not registered, skills do not exist, and there is no mechanism by which a session injects vault context or records what was touched. This change delivers the global Claude Code plugin that makes the system live: hooks that inject knowledge automatically and update the graph on writes, plus three on-demand skills that teach Claude when and how to read from and write to the vault.
|
|
|
|
## What Changes
|
|
|
|
- **New: `~/.claude/plugins/memory/` global plugin** — installs hooks (SessionStart, PostToolUse, SessionEnd) and the three skills at the user level; all projects inherit without per-project setup.
|
|
- **New: SessionStart hook** — staleness check (rebuild stamp age vs. threshold) + forced rebuild if stale; injects vault god-nodes, current-project `convention/*` summaries, episodic journal pointer, and project graph path if a project graph exists.
|
|
- **New: PostToolUse hook** (Write/Edit on vault `.md`) — runs `graphify update --file <path>` to merge changed notes into the vault graph event-driven, no polling.
|
|
- **New: SessionEnd hook** — appends a dated episodic journal note with pointers to vault notes touched in the session.
|
|
- **New: `memory-query` skill** — when/how to use `graphify query` / `path` / `explain` vs. memsearch; god-node discipline; `--budget` / `--dfs` usage; cross-client lookups via `--graph`; tag-scoped retrieval treated as a separate path from graph traversal (open question per ADR-014).
|
|
- **New: `memory-write` skill** — when knowledge is evergreen vs. project-ephemeral; required frontmatter contract (`summary` + `scope/`); vault-not-repo rule.
|
|
- **New: `memory-reorganize` skill** — plan-mode consolidation/promotion procedure; when to trigger `--force` rebuild; human-review guardrails.
|
|
- **New: plugin config block** — vault path, Graphify output dir, Ollama model name, `num_ctx`, rebuild-stale threshold (days), env vars (`OLLAMA_FLASH_ATTENTION`, `GRAPHIFY_OLLAMA_NUM_CTX`, `GRAPHIFY_OLLAMA_KEEP_ALIVE`).
|
|
|
|
**Out of scope / prerequisite (not tasks here):** Vault migration scaffolding — authoring hub notes + wikilinks — is a prerequisite for useful retrieval (ADR-014: Graphify is a structure extractor, not a topic clusterer; connectivity comes from authored hub notes + wikilinks). This change assumes that scaffolding either exists for the fixture set or will be done as a parallel prerequisite.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
|
|
- `memory-plugin-hooks`: The three lifecycle hooks (SessionStart / PostToolUse / SessionEnd) that make graph freshness and context injection automatic. Covers the shell wrapper logic, staleness check, stamp file, `graphify update --file` invocation, and journal note append.
|
|
- `memory-plugin-skills`: The three skills (`memory-query`, `memory-write`, `memory-reorganize`) that teach Claude the behavioral conventions for the memory system. Covers query-pattern guidance, frontmatter contract, write-path rules, and reorganize procedure.
|
|
|
|
### Modified Capabilities
|
|
|
|
<!-- None. This change adds the plugin runtime layer. The underlying specs (vault-graph-build,
|
|
local-model-selection, incremental-migration, reference-extraction-benchmark) are consumed
|
|
as prerequisites; their requirements do not change. -->
|
|
|
|
## Impact
|
|
|
|
- **New global plugin** at `~/.claude/plugins/memory/` (or equivalent user-level plugin install path); no per-project files created.
|
|
- **Dependencies:** Graphify (`graphifyy`, anchored to v0.8.31), Ollama with `qwen2.5-coder:7b` (or the selected model from `local-model-selection`), memsearch plugin already installed.
|
|
- **Known fragile runtime dependency:** `reasoning_effort:"none"` patch to Graphify's installed `llm.py` — lost on `pip upgrade`; tracked as a risk. Treat installed version as pinned until upstream resolves.
|
|
- **Env vars** set in plugin config: `OLLAMA_FLASH_ATTENTION=1`, `GRAPHIFY_OLLAMA_NUM_CTX=8192`, `GRAPHIFY_OLLAMA_KEEP_ALIVE=5`.
|
|
- **Consumes:** built vault graph (`vault-graph-build`), selected extraction model (`local-model-selection`), ADR-007 (lazy freshness), ADR-009 (global plugin), ADR-011 (six-facet taxonomy), ADR-013 (build-first/migrate-incrementally), ADR-014 (graph connectivity from authored structure).
|
|
- **Unblocks:** the per-project code-graph onboarding phase (Step 2e, separate change) and bulk vault migration (Step 5, separate change).
|