spec-memory

name	spec-memory
description	Indexes, searches, and injects project spec files as agent memory. Use when starting work on a spec-driven project, searching for relevant specs, recalling past design decisions, archiving spec changes, or checking spec history. Supports both directory-style specs (specs/<name>/requirements.md|design.md|tasks.md) and flat-style specs (.claude/specs/active/<name>.md).

Spec Memory

Manages the project's spec corpus as a searchable, versioned agent memory store. Backed by SQLite + FTS5 BM25 (no embedding API required). Markdown files are the source of truth; the index is reconstructable.

When to activate

Activate this skill when the user:

• starts work on a feature that might already have a spec under specs/ or .claude/specs/active/
• asks "what does the spec say about…", "why did we…", "is there prior art for…"
• writes, modifies, or wants to recall a spec
• prepares a handoff to a sub-agent and needs to inject the relevant spec context
• adds a new spec file or directory (after creation, the index needs refreshing)

Spec layouts supported

Layout	Shape	Example
Directory	specs/<name>/{readme,requirements,design,tasks,discovery,progress}.md, plus research/*.md	This project
Flat	.claude/specs/active/<name>.md (current) + .claude/specs/history/<date>-<name>-v<n>.md (archived)	The research doc's recommended layout

Both indexed by the same pipeline. The skill picks directory or file per spec at discovery time. archive only applies to flat specs (use git for directory specs).

Commands

Run from the project root. Defaults to $SPEC_MEMORY_ROOT or cwd. Pass --root <path> to override.

Initialize

npm -w @harness-visualizer/spec-memory run spec-memory -- init [--reindex]

Creates .claude/specs/{active,history}/, an empty INDEX.md, and the SQLite store at .harness-visualizer/spec-memory.db. Pass --reindex to immediately index any existing specs.

Index

npm -w @harness-visualizer/spec-memory run spec-memory -- index

Scans specs/ and .claude/specs/active/, chunks each artifact at heading boundaries, upserts into the DB with content-hash dedup, and regenerates .claude/specs/INDEX.md. Skips unchanged artifacts. Pass --force to re-chunk everything.

Search

npm -w @harness-visualizer/spec-memory run spec-memory -- search "watcher debounce" --top-k 5

Hybrid-search scaffold (RRF + BM25); v1 ships BM25 only via SQLite FTS5. Filters:

• --spec <name> — restrict to one spec
• --kind <kind> — restrict to requirements|design|tasks|discovery|research|progress|readme|spec
• --status <status> — restrict to stable|in-progress|draft|deprecated
• --format json — machine-readable output

Summarize

npm -w @harness-visualizer/spec-memory run spec-memory -- summarize <spec> [--text "..."]

Refreshes the 1-line summary for a spec in INDEX.md. Uses a heuristic (look for ## Summary / first paragraph) unless --text is passed.

Archive (flat specs only)

npm -w @harness-visualizer/spec-memory run spec-memory -- archive <spec> --summary "What changed"

Copies .claude/specs/active/<spec>.md to .claude/specs/history/<date>-<spec>-v<n>.md, bumps the version in frontmatter, prepends a "Change Summary (v → v<n+1>)" block. Directory-style specs are versioned via git instead.

Operating model

1. Markdown files are the source of truth. The SQLite DB is a cache — rm .harness-visualizer/spec-memory.db && spec-memory index rebuilds it.
2. Inject only the index, never full specs. .claude/specs/INDEX.md is the always-on payload; use search to retrieve full chunks on demand.
3. Chunk at heading boundaries. Each ## / ### heading bounds a retrieval unit, capped at ~512 tokens with line spans preserved.
4. Content-hash dedup. Re-indexing skips artifacts whose SHA-256 hasn't changed.

Token budget

• INDEX.md injection: ~1 row per spec, ~150 chars each → ~3 KB for 20 specs
• Per search result: ~300–500 tokens (chunk + 80-char heading path + source line span)
• Full spec body: load only when you're implementing against it

Spec frontmatter (optional)

Picked up when present at the top of any spec artifact:

---
name: billing-engine
status: stable          # draft | in-progress | stable | deprecated
version: 7
created: 2026-03-01
updated: 2026-05-10
depends_on:
  - auth-rbac
tags:
  - billing
---

Frontmatter is folded across artifacts within a directory-style spec: the first non-empty value wins (priority readme > spec > requirements > design > discovery > tasks > progress).

PreToolUse hook (opt-in)

To auto-inject INDEX.md at session start, add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "node ${CLAUDE_PROJECT_DIR}/.claude/skills/spec-memory/scripts/hook_inject.mjs" }
        ]
      }
    ]
  }
}

The hook is PPID-gated to fire once per session process and caps injection at ~800 tokens.

References

• references/SPEC_FORMAT.md — frontmatter fields, archive flow, history format
• Source research: .ai/research/Spec-Driven Development Memory Index Implementation Plan.md