146 lines
6.7 KiB
Markdown
146 lines
6.7 KiB
Markdown
_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 "<topic>" --budget 2000` — explore a topic
|
|
- `graphify path "<a>" "<b>"` — trace a relationship
|
|
- `graphify explain "<node>"` — deep-dive a specific node
|
|
- `graphify query "<topic>" --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 "<topic>" --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 "<question>" --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 `<project-root>/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** `<project-root>/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** `<project-root>/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
|