cc-os/openspec/changes/archive/2026-06-05-add-memory-plugin/specs/memory-plugin-skills/spec.md

ADDED 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/) 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