Archive memory-project-graph change with stable spec
Completes design and implementation of vault/project graph skill split: memory-vault (renamed from memory-query, no god-node injection), memory-project (new, covers full project-graph lifecycle), routing rule in ~/.claude/CLAUDE.md, and trimmed session-context.sh (project graph pointer only). All three AI assistant directories (.claude/, .codex/, .pi/) remain content-identical after mirroring. Spec locked and moved to openspec/specs/project-graph-lifecycle/.
This commit is contained in:
jared
parent
2317a087ce
commit
ece3469889
|
|
@ -0,0 +1,2 @@
|
||||||
|
schema: spec-driven
|
||||||
|
created: 2026-06-08
|
||||||
|
|
@ -0,0 +1,119 @@
|
||||||
|
_Last updated: 2026-06-08_
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
The memory plugin ships at `~/.claude/plugins/memory/` with three skills: `memory-query`, `memory-write`, `memory-reorganize`. `memory-query` covers vault retrieval; the other two are write-path skills. No project-graph skill exists.
|
||||||
|
|
||||||
|
Two problems compound:
|
||||||
|
|
||||||
|
1. `memory-query` has a god-node dependency: it instructs Claude to start from a hub note surfaced in the session's `additionalContext`. That requires `session-context.sh` to emit a vault graph report on every session start — cost paid regardless of whether vault knowledge is needed.
|
||||||
|
2. There is no routing rule. Claude has to infer when to query the vault versus a project graph, with no explicit guidance. The two question types are structurally distinct and need different tools.
|
||||||
|
|
||||||
|
Constraints (unchanged):
|
||||||
|
- Ollama model: `qwen2.5-coder:7b` — established by `local-model-selection`, used for all graphify extraction.
|
||||||
|
- `graphify-out/` must never be committed — local, disposable, rebuildable.
|
||||||
|
- Skills are mirrored identically across `~/.claude/`, `.codex/`, `.pi/`.
|
||||||
|
|
||||||
|
## Goals / Non-Goals
|
||||||
|
|
||||||
|
**Goals:**
|
||||||
|
- Two focused skills that align with the two query types.
|
||||||
|
- Routing rule that Claude can apply without ambiguity, persisted in a file that's globally visible.
|
||||||
|
- Lean session injection — emit only what is used on every session start.
|
||||||
|
- Remove the god-node injection dependency without breaking vault retrieval quality.
|
||||||
|
|
||||||
|
**Non-Goals:**
|
||||||
|
- Memsearch / episodic layer (Step 4 of build plan — not in scope here).
|
||||||
|
- Vault migration scaffolding (Step 1 — separate concern).
|
||||||
|
- Automated graph freshness (no daemon; updates remain on-demand).
|
||||||
|
- Bulk project onboarding.
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
|
||||||
|
### Decision: Two skills, not one with internal routing
|
||||||
|
|
||||||
|
`memory-vault` and `memory-project` are separate skills, not branches of a single skill.
|
||||||
|
|
||||||
|
The question types are structurally different: vault queries need no project context; project queries need a graph path and a codebase in scope. Skills have asymmetric capabilities — vault writes are meaningful; "project writes" are not a concept. A model routing naturally between two named skills is more reliable than a model routing internally within one skill with conditional logic.
|
||||||
|
|
||||||
|
Alternative considered: single `memory` skill with a routing section at the top. Rejected — the conditional logic would need to cover both lifecycle operations (onboard/update/remove) and query routing, making the skill unwieldy and ambiguous.
|
||||||
|
|
||||||
|
### Decision: Drop god-node injection dependency from memory-vault
|
||||||
|
|
||||||
|
The current `memory-query` skill instructs Claude to start at a hub note surfaced in `additionalContext`. Graphify's traversal already handles graph navigation internally — the `--budget` flag bounds token cost, and `graphify query` returns relevant subgraph regardless of entry node. The god-node instruction was a guard against unconstrained traversal, not a technical requirement.
|
||||||
|
|
||||||
|
Removing it means `session-context.sh` no longer needs to emit a vault graph report. The skill retains all query/path/explain patterns and the `--budget` flag, which together bound traversal cost.
|
||||||
|
|
||||||
|
Alternative considered: keep god-node but make injection opt-in. Rejected — optional injection is harder to reason about than no injection. The skill works without it.
|
||||||
|
|
||||||
|
### Decision: Routing rule lives in ~/.claude/CLAUDE.md
|
||||||
|
|
||||||
|
The routing heuristic ("vault vs project graph") must be globally visible — it applies in every project session, not just sessions in this repo. `~/.claude/CLAUDE.md` is the global user instructions file loaded automatically in every project. It is a single file to update, and changes take effect everywhere immediately.
|
||||||
|
|
||||||
|
Alternative considered: per-project CLAUDE.md. Rejected — would require maintaining the rule in every project.
|
||||||
|
|
||||||
|
Alternative considered: inside the skills themselves. Rejected — a model reading `memory-vault` might not read `memory-project` first, and vice versa. The routing rule needs a neutral home both skills can point to.
|
||||||
|
|
||||||
|
### Decision: session-context.sh emits only project graph pointer
|
||||||
|
|
||||||
|
Current `session-context.sh` emits: vault graph report, live convention query, journal pointer, project graph path. The vault graph report and convention query are the ones that motivated the god-node dependency — they pre-populate a hub node for the skill to start from. With god-node removed, they are overhead.
|
||||||
|
|
||||||
|
The project graph path pointer is the only injection that pays per-session: it tells Claude whether a project graph exists for the current repo without requiring Claude to probe the filesystem. This one conditional line remains.
|
||||||
|
|
||||||
|
Alternative considered: emit nothing; let skills query on demand. Rejected — the graph path check is cheap and eliminates a filesystem probe in every session that uses memory-project.
|
||||||
|
|
||||||
|
### Decision: memory-project delegates query mechanics to memory-vault
|
||||||
|
|
||||||
|
`memory-project`'s query section states the `--graph ./graphify-out/graph.json` routing rule and then explicitly says "see memory-vault for query mechanics (graphify query, graphify path, graphify explain, --budget, --dfs)." This avoids duplication and ensures the two skills stay consistent as graphify evolves.
|
||||||
|
|
||||||
|
### Decision: AST-only extraction for code repos; --backend ollama specified uniformly
|
||||||
|
|
||||||
|
Code repos use the free tree-sitter AST pass — no LLM cost. The `--backend ollama --model qwen2.5-coder:7b` flags are always specified on the onboard command because the single invocation handles both pure-code and mixed (code + docs) repos without requiring Claude to detect repo type first.
|
||||||
|
|
||||||
|
### Decision: cluster-only as a separate onboarding step
|
||||||
|
|
||||||
|
`graphify cluster-only .` runs after initial extraction to build the community structure required for `graphify query`. No combined command exists in the Graphify CLI at v0.8.30, so the two-step sequence is the correct protocol.
|
||||||
|
|
||||||
|
## memory-vault Skill
|
||||||
|
|
||||||
|
**Scope:** vault at `~/Documents/SecondBrain`. Evergreen, cross-project knowledge: conventions, tool behavior, client facts, patterns that generalize beyond one repo.
|
||||||
|
|
||||||
|
**Query patterns (unchanged from memory-query):**
|
||||||
|
- `graphify query "<topic>" --budget 2000` — explore
|
||||||
|
- `graphify path "<a>" "<b>"` — trace relationships
|
||||||
|
- `graphify explain "<node>"` — deep-dive
|
||||||
|
- `graphify query "<topic>" --dfs --budget 2000` — bounded depth-first
|
||||||
|
|
||||||
|
No `--graph` flag = vault default. No god-node injection needed.
|
||||||
|
|
||||||
|
**Tag-scoped caution note retained:** facet-tag graph edges not yet verified (ADR-014 open).
|
||||||
|
|
||||||
|
**Write guidance:** use memory-write when knowledge generalizes beyond the current repo. If in doubt: "Would this be useful outside this repo, next year?" If yes → vault.
|
||||||
|
|
||||||
|
## memory-project Skill
|
||||||
|
|
||||||
|
**Scope:** per-project graph at `./graphify-out/graph.json`. Codebase structure and module relationships for the current repo only.
|
||||||
|
|
||||||
|
**Lifecycle operations:**
|
||||||
|
|
||||||
|
| Operation | Command |
|
||||||
|
|-----------|---------|
|
||||||
|
| Onboard (extract) | `graphify extract . --backend ollama --model qwen2.5-coder:7b` |
|
||||||
|
| Onboard (cluster) | `graphify cluster-only .` |
|
||||||
|
| Onboard (gitignore) | ensure `graphify-out/` in `.gitignore` |
|
||||||
|
| Incremental update | `graphify update .` |
|
||||||
|
| Structural update | `graphify update . --force` (renames, deletions, moves) |
|
||||||
|
| Remove | delete `graphify-out/`; leave gitignore entry |
|
||||||
|
|
||||||
|
**Query:** `graphify query "<question>" --graph ./graphify-out/graph.json` — then see memory-vault for traversal mechanics.
|
||||||
|
|
||||||
|
**Graph path discovery:** `session-context.sh` injects the path if the graph exists. If no path is injected, suggest onboarding before knowledge queries.
|
||||||
|
|
||||||
|
**Hard constraints:** never commit `graphify-out/`; gitignore entry survives even if graph is deleted; model is `qwen2.5-coder:7b`.
|
||||||
|
|
||||||
|
## Risks / Trade-offs
|
||||||
|
|
||||||
|
- [Risk] god-node removal degrades vault retrieval quality → `--budget 2000` still bounds token cost; graphify's internal traversal handles routing from any entry. Risk is low; can be revisited if retrieval quality drops.
|
||||||
|
- [Risk] routing rule in `~/.claude/CLAUDE.md` is invisible to models that don't read it → mitigated by both skills referencing the routing rule location.
|
||||||
|
- [Risk] `graphify-out/` accidentally committed → `.gitignore` entry is step 3 of onboard; skill states "never commit" explicitly.
|
||||||
|
- [Trade-off] No automatic freshness — graphs stale after significant refactors → accepted (ADR-013 laziness principle); `graphify update .` is cheap and Claude can suggest it.
|
||||||
|
|
@ -0,0 +1,38 @@
|
||||||
|
## Why
|
||||||
|
|
||||||
|
The current memory-query skill has a god-node dependency — it assumes a hub note is surfaced in the session's `additionalContext` as an entry point. That injection relies on heavy session context output (vault graph report, convention query, journal pointer) that pays a cost every session regardless of whether vault knowledge is needed. There is also no routing rule: nothing tells Claude when to reach for the vault versus when to reach for a project graph.
|
||||||
|
|
||||||
|
On the project side, the `memory-project-graph` skill was never implemented. Per-project code graphs exist (any repo can be onboarded to Graphify), but Claude has no protocol for creating, updating, or querying them.
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
|
||||||
|
1. **Rename `memory-query` → `memory-vault`** with two changes to the SKILL.md: drop the god-node section (graphify's internal traversal handles this; no injected entry point needed), and add an explicit scope statement — this skill is for cross-project evergreen knowledge, not codebase structure.
|
||||||
|
|
||||||
|
2. **Create `memory-project`** — a new skill covering the full lifecycle of per-project Graphify graphs: onboard (extract + cluster + gitignore), incremental update, structural update (--force), remove, and project-scoped query routing. Query mechanics delegate to `memory-vault` rather than being duplicated.
|
||||||
|
|
||||||
|
3. **Add a routing rule block to `~/.claude/CLAUDE.md`** — vault for anything that generalizes beyond one repo; project graph for codebase structure and module relationships. Decision heuristic: "Would this be useful outside this repo, next year?"
|
||||||
|
|
||||||
|
4. **Trim `session-context.sh`** to emit only the project graph path pointer when `graphify-out/graph.json` exists. Drop: vault graph report, live convention query, journal pointer.
|
||||||
|
|
||||||
|
5. **Mirror** both skill renames and additions to `.codex/skills/` and `.pi/skills/` — the three AI assistant directories stay identical.
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
### New Capabilities
|
||||||
|
|
||||||
|
- `memory-vault`: Cross-project vault querying without god-node injection dependency.
|
||||||
|
- `memory-project`: Per-project graph lifecycle (onboard, update, remove) and project-scoped queries.
|
||||||
|
- `memory-routing`: Routing rule in `~/.claude/CLAUDE.md` — globally visible, single place to maintain.
|
||||||
|
|
||||||
|
### Modified Capabilities
|
||||||
|
|
||||||
|
- `session-context.sh`: Narrowed to project graph pointer only — less injection noise, faster hook execution.
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
|
||||||
|
- Rename: `~/.claude/plugins/memory/skills/memory-query/` → `memory-vault/`
|
||||||
|
- New file: `~/.claude/plugins/memory/skills/memory-project/SKILL.md`
|
||||||
|
- Edit: `session-context.sh` (trim to graph pointer)
|
||||||
|
- Edit: `~/.claude/CLAUDE.md` (add routing rule block)
|
||||||
|
- Mirror all the above to `.codex/skills/` and `.pi/skills/`
|
||||||
|
- No new runtime dependencies — same `graphify` CLI and `qwen2.5-coder:7b` Ollama model.
|
||||||
|
|
@ -0,0 +1,145 @@
|
||||||
|
_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
|
||||||
|
|
@ -0,0 +1,49 @@
|
||||||
|
## 1. Write routing rule to ~/.claude/CLAUDE.md
|
||||||
|
|
||||||
|
- [x] 1.1 Add a "Memory routing" section to `~/.claude/CLAUDE.md` with:
|
||||||
|
- Vault (`memory-vault`) for: conventions, tool behavior, client facts, patterns that generalize beyond one repo
|
||||||
|
- Project graph (`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?" — yes → vault; no → project graph
|
||||||
|
|
||||||
|
## 2. Rename memory-query → memory-vault and update SKILL.md
|
||||||
|
|
||||||
|
- [x] 2.1 Rename `~/.claude/plugins/memory/skills/memory-query/` to `memory-vault/`
|
||||||
|
- [x] 2.2 Rewrite `SKILL.md`:
|
||||||
|
- Replace description frontmatter to reflect vault scope
|
||||||
|
- Add explicit scope statement: "cross-project evergreen knowledge — not codebase structure"
|
||||||
|
- Remove the god-node section entirely (no injected hub note required)
|
||||||
|
- Keep: query/path/explain patterns with `--budget 2000`, tag-scoped caution note (ADR-014), episodic → memsearch redirect
|
||||||
|
- Add write guidance: use `memory-write` for knowledge that generalizes; decision heuristic points to `~/.claude/CLAUDE.md` routing rule
|
||||||
|
|
||||||
|
## 3. Create memory-project skill
|
||||||
|
|
||||||
|
- [x] 3.1 Create directory `~/.claude/plugins/memory/skills/memory-project/`
|
||||||
|
- [x] 3.2 Write `SKILL.md` with sections:
|
||||||
|
- **Scope** — project graph at `./graphify-out/graph.json`; codebase structure only
|
||||||
|
- **Onboard** — `graphify extract . --backend ollama --model qwen2.5-coder:7b`, then `graphify cluster-only .`, then add `graphify-out/` to `.gitignore`; note AST-only cost for code repos; confirm graph.json exists before reporting done
|
||||||
|
- **Incremental update** — `graphify update .` for routine edits; `graphify update . --force` for structural changes (renames, deletions, moves); suggest update after major refactors
|
||||||
|
- **Remove** — delete `graphify-out/`; graph is rebuildable; leave gitignore entry
|
||||||
|
- **Query** — `graphify query "<question>" --graph ./graphify-out/graph.json`; delegate traversal mechanics to `memory-vault` (no duplication)
|
||||||
|
- **Graph path discovery** — `session-context.sh` injects path if graph exists; if no path injected in project context, suggest onboard
|
||||||
|
- **Constraints** — never commit `graphify-out/`; model is `qwen2.5-coder:7b`; gitignore entry survives deletion
|
||||||
|
|
||||||
|
## 4. Trim session-context.sh
|
||||||
|
|
||||||
|
- [x] 4.1 Edit `~/.claude/plugins/memory/hooks/session-context.sh`:
|
||||||
|
- Remove: vault graph report output, live convention query, journal pointer
|
||||||
|
- Keep: conditional check for `<project-root>/graphify-out/graph.json`; if exists, emit the absolute path; else emit nothing
|
||||||
|
|
||||||
|
## 5. Mirror to .codex/ and .pi/
|
||||||
|
|
||||||
|
- [x] 5.1 Rename `.codex/skills/memory-query/` → `memory-vault/`; replace SKILL.md with the updated content from step 2
|
||||||
|
- [x] 5.2 Create `.codex/skills/memory-project/SKILL.md` with the content from step 3
|
||||||
|
- [x] 5.3 Rename `.pi/skills/memory-query/` → `memory-vault/`; replace SKILL.md with the updated content from step 2
|
||||||
|
- [x] 5.4 Create `.pi/skills/memory-project/SKILL.md` with the content from step 3
|
||||||
|
|
||||||
|
## 6. Verify against spec
|
||||||
|
|
||||||
|
- [x] 6.1 Check Requirement 1: routing rule exists in `~/.claude/CLAUDE.md` with vault/project distinction and decision heuristic
|
||||||
|
- [x] 6.2 Check Requirement 2: `memory-vault` SKILL.md has no god-node section; has scope statement; query patterns present; tag-caution retained
|
||||||
|
- [x] 6.3 Check Requirement 3: `memory-project` SKILL.md covers all lifecycle operations; query delegates to memory-vault; constraints stated; gitignore contract explicit
|
||||||
|
- [x] 6.4 Check Requirement 4: `session-context.sh` emits only the graph path pointer; vault report, convention query, journal pointer are gone
|
||||||
|
- [x] 6.5 Check Requirement 5: content of `memory-vault/SKILL.md` and `memory-project/SKILL.md` is identical across `~/.claude/plugins/memory/skills/`, `.codex/skills/`, `.pi/skills/`
|
||||||
|
|
@ -0,0 +1,145 @@
|
||||||
|
_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
|
||||||
Loading…
Reference in New Issue