hyper-memory git:20260701.cfc527cA

Immutable. This exact content is served forever at /api/v1/blob/d74b132b7fc3b055.

---
name: hyper-memory
description: Use on-demand to extract evidence-anchored repo-local knowledge candidates from accumulated .hyperclaude/ artifacts (plans/done, plan-reviews, research) and curate them. Also when the user invokes /hyperclaude:hyper-memory. Orchestration-only — no Codex spawn.
---

# hyper-memory

Repo-local knowledge extraction. Scans the accumulated `.hyperclaude/` corpus and writes one evidence-anchored candidate markdown file per deterministic copy-based span under `.hyperclaude/memory/candidates/`. v1 is **extraction + curation only** — auto-injection into future sessions is the v2 north star and is explicitly out of scope here.

## When to use

- User typed `/hyperclaude:hyper-memory` (with or without an argument).
- A batch of work has accumulated in `.hyperclaude/` (several archived plans, plan-reviews, research artifacts) and it's worth mining for durable repo-local knowledge.

## When to skip

- Only a single small artifact exists since the last extraction — not enough accumulated corpus to be worth mining.
- You want the knowledge injected automatically into a session — that's v2, not implemented.

## How it works

1. Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory/extract.mjs"` via Bash and parse the one-line JSON summary it prints to stdout: `{ ok, scanned, candidates, written, skipped, errored, candidatesDir }`.

   The script's CLI accepts exactly two flags — no others exist:
   - `--dry-run` — compute candidates and keys but write nothing (`written` is always `0`).
   - `--root <path>` — corpus root to scan (default `.hyperclaude`).

2. It fully enumerates the v1 source allowlist — NOT newest-only:
   - `plans/done/` — every archived plan.
   - `plan-reviews/` — every plan-review artifact whose verdict is `Ship as-is`.
   - `research/` — every research artifact.

   `code-reviews/` and `docs-reviews/` are v1 non-goals and are never scanned.

3. It writes one evidence-anchored markdown file per candidate under `.hyperclaude/memory/candidates/`, keyed by a compound hash so re-runs are idempotent: a candidate is skipped if its key already exists in EITHER `.hyperclaude/memory/candidates/` OR `.hyperclaude/memory/promoted/` — an already-promoted candidate is never resurrected.

## Candidate schema

Each candidate file's YAML frontmatter carries exactly these keys, in this order:

`plugin-version`, `type`, `source-artifact`, `anchors`, `mode`, `slug`, `git-head`, `generated`, `staleness`

followed by a `## Claim` (a deterministically templated one-liner) and a `## Evidence` section holding **strictly the verbatim copied span** — never a generated or derived line.

**CORE POLICY:** artifact sentences are never stored as truth on their own — every candidate carries an inline evidence anchor quoted verbatim from `source-artifact:`, so a claim can always be traced back to the exact text it came from.

Two fields are easy to conflate and must be read as distinct:

- `source-artifact:` — the `.hyperclaude/**` artifact path the candidate was **mined from** (evidence provenance; a gitignored artifact, not a canonical repo source).
- `anchors:` — a YAML list of **live canonical repo source/doc paths** the claim is *about*. **The extractor ALWAYS emits `anchors: []`** — none of the three v1 sources deterministically names a real repo file, and a `.hyperclaude/**` path is NEVER a valid `anchors:` entry.

## Curation

Two locations only — no multi-state machine:

- `.hyperclaude/memory/candidates/` — proposed, unreviewed.
- `.hyperclaude/memory/promoted/` — human-accepted.

**Promote:** plain `mv .hyperclaude/memory/candidates/<file> .hyperclaude/memory/promoted/<file>` — NOT `git mv` (`.hyperclaude/` is gitignored, so git tracks neither side).

**Promotion gate:** every candidate ships with `anchors: []`. Before promoting, the curator MUST add at least one real repo source/doc path (a non-`.hyperclaude/` file that exists on disk) to the candidate's `anchors:` list. `source-artifact:` provenance alone never satisfies this gate — it names a gitignored artifact, not a canonical anchor.

**Reject:** `rm` the candidate file.

**Idempotency:** because promotion is a plain move out of `candidates/`, and the extractor checks BOTH `candidates/` and `promoted/` for an existing key, a promoted candidate is never re-created by a later extraction run.

## Invocation argument

**Invocation argument:** $ARGUMENTS

**Accepted argument grammar — nothing outside this table:**

| Token(s)          | Meaning                                    |
|-------------------|---------------------------------------------|
| `--dry-run`       | compute candidates/keys, write nothing       |
| `--root <path>`   | corpus root to scan (default `.hyperclaude`) |

The script's CLI parser rejects anything else (unknown flags, `--root` with a missing/flag-like value) with `{"ok":false,"error":...}` and a non-zero exit — see `scripts/memory/extract.mjs`.

Do NOT interpolate the raw `$ARGUMENTS` string into the Bash command. Parse it into individual tokens, keep only tokens matching the grammar above, and pass each as its own shell-quoted argument (e.g. quote the `--root` path value) when invoking `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory/extract.mjs"`. Any token outside the grammar means: do not pass it through — the script would reject it anyway.