diff --git a/openspec/changes/archive/2026-06-08-memory-project-graph/.openspec.yaml b/openspec/changes/archive/2026-06-08-memory-project-graph/.openspec.yaml new file mode 100644 index 0000000..e8d4ccf --- /dev/null +++ b/openspec/changes/archive/2026-06-08-memory-project-graph/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-06-08 diff --git a/openspec/changes/archive/2026-06-08-memory-project-graph/design.md b/openspec/changes/archive/2026-06-08-memory-project-graph/design.md new file mode 100644 index 0000000..8cfd4f9 --- /dev/null +++ b/openspec/changes/archive/2026-06-08-memory-project-graph/design.md @@ -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 "" --budget 2000` — explore +- `graphify path "" ""` — trace relationships +- `graphify explain ""` — deep-dive +- `graphify query "" --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 "" --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. diff --git a/openspec/changes/archive/2026-06-08-memory-project-graph/proposal.md b/openspec/changes/archive/2026-06-08-memory-project-graph/proposal.md new file mode 100644 index 0000000..14d37b3 --- /dev/null +++ b/openspec/changes/archive/2026-06-08-memory-project-graph/proposal.md @@ -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. diff --git a/openspec/changes/archive/2026-06-08-memory-project-graph/specs/project-graph-lifecycle/spec.md b/openspec/changes/archive/2026-06-08-memory-project-graph/specs/project-graph-lifecycle/spec.md new file mode 100644 index 0000000..57e3f84 --- /dev/null +++ b/openspec/changes/archive/2026-06-08-memory-project-graph/specs/project-graph-lifecycle/spec.md @@ -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 "" --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 diff --git a/openspec/changes/archive/2026-06-08-memory-project-graph/tasks.md b/openspec/changes/archive/2026-06-08-memory-project-graph/tasks.md new file mode 100644 index 0000000..125c02a --- /dev/null +++ b/openspec/changes/archive/2026-06-08-memory-project-graph/tasks.md @@ -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 "" --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 `/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/` diff --git a/openspec/specs/project-graph-lifecycle/spec.md b/openspec/specs/project-graph-lifecycle/spec.md new file mode 100644 index 0000000..57e3f84 --- /dev/null +++ b/openspec/specs/project-graph-lifecycle/spec.md @@ -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 "" --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