# Spec: memory-plugin-skills

_Purpose: Define the Claude Code skill behaviors for the memory plugin — when and how to query the vault graph, write vault knowledge, and reorganize vault notes._

_Last updated: 2026-06-05_

---

## Requirements

### Requirement: memory-query skill — graph retrieval guidance
The plugin SHALL provide a `memory-query` skill that teaches Claude when and how to query the vault knowledge graph versus the episodic memsearch layer. The skill SHALL specify: (a) use `graphify query "<topic>"` for evergreen knowledge questions ("how do we…", "what do we know about…"), (b) use `graphify path "<node-a>" "<node-b>"` to find how two concepts relate, (c) use `graphify explain "<node>"` for a deep-dive with neighbors, (d) add `--budget N` to cap answer size (default ~2000 tokens), (e) add `--dfs --budget N` for bounded depth-first traversal, (f) add `--graph <path>` to query a specific project graph instead of the vault graph. The skill SHALL explicitly state that god-nodes are the entry point — query god-nodes first, then scalpel to specific nodes. The skill SHALL treat tag-scoped retrieval (e.g. "all notes tagged `client/acme`") as a SEPARATE query path from graph traversal, noting that whether shared frontmatter facet tags create graph edges is unverified (ADR-014 open question); Claude SHALL NOT assume facet tags enable graph traversal. For "what happened when" questions, the skill SHALL direct Claude to memsearch in natural language rather than the vault graph.

#### Scenario: Claude needs to answer a knowledge question during a task
- **WHEN** a task touches a tool, client, or domain the vault may know about
- **THEN** Claude runs `graphify query "<topic>"` before relying on training knowledge, using `--budget` to keep context lean

#### Scenario: Claude needs to find how two concepts relate
- **WHEN** a task requires understanding the relationship between two vault entities (e.g. client and a tool they use)
- **THEN** Claude runs `graphify path "<entity-a>" "<entity-b>"` to traverse the graph path between them

#### Scenario: Cross-client knowledge lookup
- **WHEN** Claude needs to find all vault knowledge about a tool or domain regardless of which client it came from
- **THEN** Claude runs `graphify query "<tool-or-domain>"` against the vault graph (not `--graph <project-path>`) to get cross-client results

#### Scenario: Project-specific knowledge lookup
- **WHEN** Claude needs knowledge specific to the current project's code graph
- **THEN** Claude runs `graphify query "<topic>" --graph <project-root>/graphify-out/graph.json` using the project graph path injected by SessionStart

#### Scenario: Episodic question ("what was I working on last week?")
- **WHEN** a question is time-anchored ("what did we decide last Tuesday", "what was I working on yesterday")
- **THEN** Claude queries memsearch in natural language, NOT the vault graph

### Requirement: memory-write skill — when and how to write vault knowledge
The plugin SHALL provide a `memory-write` skill that teaches Claude when knowledge should be written to the vault and what the required frontmatter contract is. The skill SHALL specify: write to the vault when knowledge is evergreen and reusable across projects (tool/API behavior, conventions, client-specific facts worth reusing); do NOT write project-ephemeral state to the vault (that goes to project files or the episodic layer). The skill SHALL specify the required frontmatter fields: `summary` (one-line, written at note creation — not deferred — this is the human-authored router hint Graphify does not generate), `scope/global` or `scope/project` (default new tool/domain knowledge to `scope/global`; use `scope/project` when specific to how a client uses something), and at least one facet tag from the six-facet taxonomy (`type/`, `client/`, `project/`, `domain/`, `tool/`, `convention/`). The skill SHALL state the vault-not-repo rule: write knowledge ONLY to `~/Documents/SecondBrain`, never silently into a project repo. The skill SHALL note that writing a vault note automatically triggers the PostToolUse hook to update the graph — no manual graphify call is needed after writing.

#### Scenario: Claude discovers how a tool's API behaves
- **WHEN** Claude learns something about a tool's authentication, rate limits, or endpoint quirks that could apply to future sessions or projects
- **THEN** Claude writes a note to the vault with the required frontmatter (summary, scope/global, type/reference, tool/<name>) rather than embedding it in the project's CLAUDE.md

#### Scenario: Claude establishes a convention that should apply beyond this task
- **WHEN** Claude and the user settle on a convention (coding style, workflow, decision rule) that should propagate to other projects
- **THEN** Claude writes a `convention/<name>` note to the vault with the required frontmatter (summary, scope, type/convention)

#### Scenario: Knowledge is project-specific (how this client uses a tool)
- **WHEN** the knowledge describes behavior specific to one client's setup, not the tool generally
- **THEN** Claude writes the note with `scope/project` and a `client/<name>` facet tag rather than `scope/global`

#### Scenario: Claude tries to record project-ephemeral state
- **WHEN** the information is specific to the current task and not reusable in future sessions or projects
- **THEN** Claude does NOT write it to the vault; it stays in the project repo or episodic session notes

### Requirement: memory-reorganize skill — consolidation and plan-mode promotion
The plugin SHALL provide a `memory-reorganize` skill that teaches Claude the procedure for consolidating, deduplicating, promoting, and reorganizing vault notes. The skill SHALL specify: (a) reorganization MUST happen in plan mode — Claude proposes changes for human review before executing; (b) triggers include: duplicate coverage noticed across notes, a `scope/project` fact observed to recur across 2+ clients (promotion candidate), a note grown beyond the L1 "one concept, ~200 lines" discipline; (c) the consolidation procedure is: identify candidate notes, propose a merge/split/promote/rename plan, await human approval, execute edits, then run `graphify extract <vault-path> --force` to rebuild the graph clean; (d) a `--force` rebuild is required after any reorganization that removes, renames, or restructures notes (to clear ghost nodes); (e) `--force` rebuild is ALSO triggered when the SessionStart stale check fires, so reorganize skill's rebuild invocation is consistent with the staleness-check mechanism. The skill SHALL warn that `graphify update --file` does NOT prune deleted or renamed nodes — only `--force` rebuilds clear ghost nodes.

#### Scenario: Claude notices duplicate coverage across two vault notes
- **WHEN** Claude identifies two notes that cover the same concept with overlapping content
- **THEN** Claude enters plan mode: proposes which note to keep, what to merge, and what to discard — and awaits human approval before making any edits

#### Scenario: A project-scoped fact has recurred across multiple clients
- **WHEN** Claude observes that a fact tagged `scope/project` has appeared in 2+ client contexts, suggesting it is actually global knowledge
- **THEN** Claude proposes promoting the note to `scope/global` (updating frontmatter, merging client-specific variants if needed) in plan mode before executing

#### Scenario: Reorganization is complete and graph needs to be rebuilt
- **WHEN** any reorganization edit has been approved and executed (notes deleted, renamed, or restructured)
- **THEN** Claude runs `graphify extract <vault-path> --backend ollama --model <configured-model> --force` to clear ghost nodes and rebuild a clean graph; updates the rebuild stamp

#### Scenario: Note has grown beyond single-concept discipline
- **WHEN** Claude observes a vault note has grown beyond ~200 lines or covers more than one distinct concept
- **THEN** Claude proposes a split into two or more focused notes in plan mode, with proposed filenames, frontmatter, and the wikilinks that would connect them — before executing
