_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.py`. 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.py` 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.py
- **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.py trimmed to project graph pointer

`session_context.py` SHALL emit only:
- The absolute path to `<project-root>/graphify-out/graph.json` — if and only if that file exists

`session_context.py` SHALL NOT emit:
- Vault graph reports
- Live convention queries
- Journal pointers

#### Scenario: session_context.py 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.py 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 (`cc-os/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
