_Last updated: 2026-06-08_ ## Scope This spec covers the refactored memory skill layout: `memory-vault` (renamed from `memory-query`), `memory-project` (new), the routing rule in `~/.claude/CLAUDE.md`, and the trimmed `session-context.sh`. The original spec name (project-graph-lifecycle) is retained for path stability. --- ## Requirement 1: Routing rule in ~/.claude/CLAUDE.md A routing rule block SHALL be added to `~/.claude/CLAUDE.md` that tells Claude: - Use `memory-vault` for: conventions, tool behavior, client facts, patterns that generalize beyond one repo. - Use `memory-project` for: codebase structure, module relationships, what exists where in the current repo. - Decision heuristic: "Would this be useful outside this repo, next year?" — if yes, vault; if no, project graph. #### Scenario: Claude chooses between vault and project graph - **WHEN** Claude needs to answer a question about tool conventions or client context - **THEN** Claude uses `memory-vault` (vault query, no `--graph` flag) - **WHEN** Claude needs to answer a question about what modules exist in the current codebase - **THEN** Claude uses `memory-project` with `--graph ./graphify-out/graph.json` --- ## Requirement 2: memory-vault skill The `memory-vault` SKILL.md SHALL: 2.1 State explicitly that this skill is for cross-project evergreen knowledge — not codebase structure. 2.2 Provide query patterns: - `graphify query "" --budget 2000` — explore a topic - `graphify path "" ""` — trace a relationship - `graphify explain ""` — deep-dive a specific node - `graphify query "" --dfs --budget 2000` — bounded depth-first 2.3 NOT contain a god-node section or any instruction to start from an injected hub note. Graph traversal entry point is handled internally by graphify. 2.4 Retain the tag-scoped caution note: facet-tag graph edges are not yet verified (ADR-014 open); treat tag-based filtering as experimental. 2.5 Include write guidance pointing to `memory-write` with the routing heuristic. #### Scenario: Claude queries the vault without injected context - **WHEN** no vault graph report is present in session context - **THEN** Claude runs `graphify query "" --budget 2000` directly - **AND** Claude does NOT stall waiting for a god-node entry point #### Scenario: Claude stays in vault scope for cross-project questions - **WHEN** the question concerns client conventions or tool behavior - **THEN** Claude queries the vault (no `--graph` flag) - **AND** Claude does NOT use `--graph ./graphify-out/graph.json` for this question --- ## Requirement 3: memory-project skill The `memory-project` SKILL.md SHALL: 3.1 Cover the **onboard** lifecycle: - `graphify extract . --backend ollama --model qwen2.5-coder:7b` (from project root) - `graphify cluster-only .` (build community structure for query) - Ensure `graphify-out/` is present in `.gitignore` - Confirm `graphify-out/graph.json` exists before reporting complete - State that code-only repos use the free AST pass; LLM cost only applies when `.md` docs are present 3.2 Cover **incremental update**: - `graphify update .` for routine edits (no `--force`) - `graphify update . --force` for structural changes (renames, deletions, directory moves) - Suggest update after sessions involving significant refactoring 3.3 Cover **remove**: - Delete `graphify-out/` when project is inactive or graph is too stale - Confirm the graph is always rebuildable via the onboard sequence - Leave the `.gitignore` entry even after removal 3.4 Cover **query routing**: - Use `graphify query "" --graph ./graphify-out/graph.json` - Delegate all query mechanics (traversal, --budget, --dfs, graphify path, graphify explain) to `memory-vault` — do not duplicate 3.5 Cover **graph path discovery**: - `session-context.sh` injects the graph path when `graphify-out/graph.json` exists - If no graph path is injected and Claude is in a project context, suggest running the onboard sequence before proceeding with knowledge queries 3.6 State hard constraints: - Never commit `graphify-out/` - Model is `qwen2.5-coder:7b` - `.gitignore` entry for `graphify-out/` must survive even if the directory is deleted #### Scenario: Claude onboards a new project - **WHEN** a user asks to onboard a project to the memory system - **THEN** Claude runs extract, then cluster-only, then adds the gitignore entry - **AND** Claude confirms graph.json exists before reporting done - **AND** Claude does NOT commit graphify-out/ under any circumstances #### Scenario: Claude updates the graph after routine edits - **WHEN** files have been modified but not renamed, deleted, or moved - **THEN** Claude runs `graphify update .` (no `--force`) #### Scenario: Claude updates the graph after structural changes - **WHEN** files have been renamed, deleted, or directories reorganized - **THEN** Claude runs `graphify update . --force` to clear ghost nodes #### Scenario: Claude starts a session in a project with no graph - **WHEN** no graph path is injected by session-context.sh - **AND** Claude is working in a project context - **THEN** Claude suggests the onboard sequence before knowledge queries - **AND** Claude does NOT silently fall back to vault-only retrieval without noting the gap --- ## Requirement 4: session-context.sh trimmed to project graph pointer `session-context.sh` SHALL emit only: - The absolute path to `/graphify-out/graph.json` — if and only if that file exists `session-context.sh` SHALL NOT emit: - Vault graph reports - Live convention queries - Journal pointers #### Scenario: session-context.sh runs in an onboarded project - **WHEN** `/graphify-out/graph.json` exists - **THEN** the script outputs the absolute path to the graph file - **AND** no other memory context is emitted #### Scenario: session-context.sh runs in a project with no graph - **WHEN** `/graphify-out/graph.json` does not exist - **THEN** the script outputs nothing (or a minimal "no project graph" note) --- ## Requirement 5: Mirror to .codex/ and .pi/ 5.1 `.codex/skills/memory-query/` SHALL be renamed to `.codex/skills/memory-vault/` with the same SKILL.md content as `~/.claude/plugins/memory/skills/memory-vault/`. 5.2 `.codex/skills/memory-project/SKILL.md` SHALL be created with the same content as `~/.claude/plugins/memory/skills/memory-project/SKILL.md`. 5.3 Same renames and additions SHALL be applied to `.pi/skills/`. 5.4 All three directories (`~/.claude/plugins/memory/skills/`, `.codex/skills/`, `.pi/skills/`) SHALL remain content-identical after this change. #### Scenario: Verifying mirror consistency - **WHEN** any of the three skill directories is read - **THEN** the content of `memory-vault/SKILL.md` is identical across all three - **AND** the content of `memory-project/SKILL.md` is identical across all three