# Hyper Memory

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-zeikar-hyperclaude-hyper-memory`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zeikar](https://agentstack.voostack.com/s/zeikar)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zeikar](https://github.com/zeikar)
- **Source:** https://github.com/zeikar/hyperclaude/tree/main/skills/hyper-memory
- **Website:** http://zeikar.dev/hyperclaude/

## Install

```sh
agentstack add skill-zeikar-hyperclaude-hyper-memory
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 ` — 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/ .hyperclaude/memory/promoted/` — 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 `   | 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zeikar](https://github.com/zeikar)
- **Source:** [zeikar/hyperclaude](https://github.com/zeikar/hyperclaude)
- **License:** MIT
- **Homepage:** http://zeikar.dev/hyperclaude/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zeikar-hyperclaude-hyper-memory
- Seller: https://agentstack.voostack.com/s/zeikar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.