| name | cache |
| description | Use when the user wants to view, search, add, edit, prune, archive, or clear hyperflow memory entries. CRUD interface for `.hyperflow/memory/` — never modifies source code, only memory files.
Trigger with /hyperflow:cache, hyperflow cache, "show memory", "search memory for X", "clear memory", "what does hyperflow remember about Y".
|
| allowed-tools | Read, Write, Edit, Bash(ls:*), Bash(mv:*), Bash(rm:*), Glob, Grep, Agent, AskUserQuestion |
| argument-hint | <show|search|add|edit|prune|archive|clear|stats|migrate|off|compact> [args] |
| version | 5.14.0 |
| license | MIT |
| compatibility | Claude Code · Codex · OpenCode · Grok · Antigravity (memory files are project-local) |
| tags | ["memory","persistence","project-state"] |
Cache
CRUD interface for .hyperflow/memory/. Full protocol: memory-system.md. Semantic ops and gate fallbacks: runtime-contract.md.
Storage
All operations target .hyperflow/memory/ at the project root. Never modify source code files — if asked to "remember X about file Y", add a memory entry only, never edit Y.
Subcommands
| Subcommand | Description |
|---|
show [tag] | Print index or filter entries by tag |
search <query> | Full-text search across all memory files |
add <category> <title> | Append a new entry (prompts for details) |
edit <entry-id> | Find entry by date+title slug and update in place |
prune | Remove stale, superseded, and orphaned entries |
archive | Move entries older than 30 days to cold storage |
clear | Wipe all memory (with confirmation, recoverable) |
stats | Counts, tier breakdown, tag frequency, oldest/newest |
migrate | Import entries from legacy global memory files when present |
off | Disable memory writes for this session |
compact | Summarise aged memory entries into stubs + monthly archive sidecars |
Subcommand Details
show [tag]
No arg → print index.md. With tag → filter all files for matching entries.
Output table: Date | Title | Tags | File | Tier
search <query>
grep/ripgrep across learnings.md, decisions.md, pitfalls.md, patterns.md, conventions.md.
Return file:line + snippet, ranked by relevance. Prefer host grep / ripgrep via the shell op when available; otherwise read files and scan inline. Do not invent matches.
add <category> <title>
Categories: learning decision pitfall pattern convention
Collect details via structured_question (prefer native structured question UI / AskUserQuestion when present): what, why it matters, tags (controlled vocab).
When structured input is absent (no popup / no request_user_input / no host question tool):
- Print the exact Hyperflow Question chat block from runtime-contract.md for each required field (or one multi-field prompt with numbered options where choices are discrete).
- End the turn and wait for the user's answer.
- Never invent what/why/tags and append silently. Never pick a recommended default for free-form fields.
After answers arrive, append to the matching file using:
### [YYYY-MM-DD] <title> `[tag1, tag2]`
**What:** ...
**Why it matters:** ...
**Evidence:** ...
That is the whole write. index.md is derived — scripts/memory-index.py rebuilds it at the next session start. Never append index rows by hand; to refresh it now, run python3 <plugin-root>/scripts/memory-index.py .hyperflow when the script is available (resolve plugin root like bridge: $CODEX_PLUGIN_ROOT / $CLAUDE_PLUGIN_ROOT / … / path relative to this skill).
edit <entry-id>
Locate by date+title slug. Show current value, prompt for new value via structured_question (same portable fallback as add), update in place. No silent overwrite without the new value from the user.
prune
Per memory-system.md pruning protocol:
- Remove
[SUPERSEDED] entries older than 7 days
- Remove entries whose referenced files no longer exist (
test -f / host file check)
- Archive entries unreferenced 90+ days to
.hyperflow/memory/archive/YYYY-MM.md
Print summary of removed/archived counts.
archive
Compress hot entries older than 30 days → .hyperflow/memory/archive/YYYY-MM.md.
Leave one-line summary in original file. The stub keeps its date, so the derived index re-tiers it to cold on its own.
clear (STRUCTURAL DESTRUCTIVE GATE — never silent)
Always confirm before any wipe. This is a structural irreversibility-adjacent gate: autonomy directives do not skip it.
- Prefer
structured_question / native question UI with a binary action gate (no (Recommended) marker):
This wipes all memory for this project. Are you sure?
Yes — move everything to archive/cleared-<timestamp>.md then reset category stubs
No — leave memory untouched
- If structured input is absent: print the same options as a
Hyperflow Question chat block and end the turn. Do not delete, move, or truncate any memory file until the user answers.
- If no interactive channel at all (headless): refuse. Print
clear requires interactive confirmation and stop. Do not wipe.
- On Yes only → move all content to
.hyperflow/memory/archive/cleared-<timestamp>.md, then reset category files to empty stubs. On No → print Clear cancelled and stop.
Silent defaulting of this gate is a doctrine / runtime-contract violation.
stats
Print: total entries, hot/warm/cold counts, tag frequency table, oldest and newest entry dates. When entry timestamps are missing, print unavailable for those fields — never fabricate dates.
migrate
Import from legacy global memory when readable:
- Prefer
~/.claude/hyperflow-memory.md if present (historical Claude install).
- Also accept project-local legacy paths documented in memory-system when present.
- Filter entries matching the current project path; append matching entries to
learnings.md tagged [migrated]. Leave source files untouched.
- Print count of migrated entries + source path(s).
- If no source found: print
(nothing to migrate — no legacy memory file found) and stop. Not an error.
Do not require Claude-only paths when they are absent; do not invent migrated content.
off
Print: "Memory writes disabled for this session." No files modified.
compact
User-invoked memory compaction. Summarises entries older than 7 days into stub lines and preserves the full text in monthly archive sidecars at .hyperflow/memory/archive/YYYY-MM.md.
Flow:
- The compact subcommand handler reads the target memory file (default:
learnings.md; pass a path to target another).
- The Date/tag parser splits entries into hot (≤7 days, preserved) and eligible (>7 days). Both
[domain, type] and legacy backticked `[domain, type]` tag forms are accepted.
- Compaction Writer — prefer
spawn for an independent writer child when the host collaboration inventory exposes it; otherwise run a labelled inline worker phase (Worker — compacting memory entries). Never require an unmapped Claude-only Agent API as the sole path (runtime-contract.md).
- The Stub formatter renders each replacement line as
### [YYYY-MM-DD] Short title [domain, type] — summarized, see archive/YYYY-MM.md.
- Dedup Reviewer — separate
spawn or labelled inline reviewer phase (**Reviewer** — memory compact dedup). Source-side stub-line match and archive-side header match (date + title + tags). Workers never self-review.
- The Archive-sidecar writer appends accepted entries to
archive/YYYY-MM.md, grouped by each entry's calendar month.
- The source file is rewritten with stubs replacing the original entries.
- Refresh
.hyperflow/memory/.checksums (memory-scoped sidecar — distinct from .hyperflow/.checksums which scaffold staleness owns) when that sidecar is in use, then print a summary.
Output: N entries compacted into archive/YYYY-MM.md · M stubs rejected as duplicates · source N→M lines. Full protocol in compaction.md.
Flow
- Parse invocation to determine subcommand
- If subcommand missing → list subcommands table above with one-line descriptions
- Execute subcommand (gates use
structured_question → Hyperflow Question → refuse; never silent default)
- Print structured result with counts/changes summary
Overview
/hyperflow:cache (alias: hyperflow cache) is the operator interface to project-scoped memory under .hyperflow/memory/. It's the only skill that mutates memory files directly (other skills append via the memory-system protocol). Subcommands cover the full lifecycle: show, search, add, edit, prune, archive, clear, stats, migrate, compact. All operations are project-local — entries never leak across projects.
Prerequisites
.hyperflow/ initialized (run /hyperflow:scaffold if missing — cache creates .hyperflow/memory/ on first write but expects the parent dir).- Write access to
.hyperflow/memory/ and .hyperflow/memory/archive/ for mutating subcommands.
- For
migrate only: read access to a legacy memory file when one exists.
Instructions
- Parse the subcommand from the user's invocation (or list subcommands if none given). Portable hosts accept
/hyperflow:cache … and hyperflow cache … equally (SKILL.md router).
- Validate prerequisites for the chosen subcommand (
clear / add / edit require a real user answer before mutation; never invent answers).
- Execute against
.hyperflow/memory/ using host edit / shell ops when available.
- Print structured result with counts and any file-level changes.
Output
Each subcommand prints a compact summary:
show — table of matching entries (Date | Title | Tags | File | Tier).search — file:line matches with snippets, ranked by relevance.add / edit — confirmation line with new entry id and target file (only after answered prompts).prune / archive / clear — counts of removed/archived/cleared entries plus destination paths.stats — totals + hot/warm/cold breakdown + top-N tags.migrate — count of migrated entries + source path(s).off — single-line Memory writes disabled for this session.compact — compaction counts + archive path.
Error Handling
| Failure | Behavior |
|---|
.hyperflow/memory/ missing | Auto-create skeleton (category files + archive/.gitkeep) on first write; for read-only subcommands, print (no memory yet — invoke /hyperflow:scaffold first). |
| Subcommand unknown | Print subcommands table; suggest closest match via Levenshtein distance. |
add with invalid category | Reject and list valid categories: learning, decision, pitfall, pattern, convention. |
edit entry id not found | List 3 closest matches by title slug + date. |
clear / add / edit without structured input | Hyperflow Question chat block + end turn; no mutation until answered. |
clear without confirmation (headless / no channel) | Refuse and print clear requires interactive confirmation. Do not wipe. |
migrate source file missing | Print (nothing to migrate — no legacy memory file found) and stop. |
spawn unavailable during compact | Labelled inline worker then separate inline reviewer; same stub/dedup rules. |
| Shell / edit op unavailable | Refuse the mutating subcommand with edit/shell unavailable; do not claim files changed. |
Examples
Show all entries
/hyperflow:cache show
Date Title Tags File Tier
2026-05-16 Bash scoping required by validator [validator, marketplace] learnings.md hot
2026-05-15 No AI attribution in commits [convention, git] conventions.md hot
2026-05-14 Per-task commits in plugin dev [convention, git] conventions.md hot
3 entries (3 hot, 0 warm, 0 cold)
Search
hyperflow cache search "validator"
.hyperflow/memory/learnings.md:42 — "Jeremy's validator requires scoped Bash..."
.hyperflow/memory/decisions.md:8 — "...validator score of 73 → 94 after fix"
2 matches
Clear without structured UI (portable)
/hyperflow:cache clear
Hyperflow Question
This wipes all memory for this project. Are you sure?
1. Yes — move everything to archive/cleared-<timestamp>.md then reset category stubs
2. No — leave memory untouched
[end turn — no files modified until the user answers]
Add a learning
/hyperflow:cache add learning "Markdown frontmatter needs block scalar for colons"
? What: Block scalar (|) preserves : and backticks in YAML values
? Why it matters: prevents fatal YAML parse failures in marketplace validators
? Tags: yaml, validator, frontmatter
Added — .hyperflow/memory/learnings.md (entry 2026-05-16-block-scalar-frontmatter)
Stats
/hyperflow:cache stats
Memory entries: 47
Hot (≤7d) 12
Warm (8-30d) 23
Cold (30d+) 12
Top tags: validator (8), convention (7), git (6), yaml (4)
Oldest: 2026-02-14 Newest: 2026-05-16
Resources
- memory-system.md — full protocol: files, tiers, tagging, pruning rules.
- artefact-data.md — viewer mode: memory entries are the leaner
{title, task, decision, tags} shape (tags required for tag-matched injection), viewable as a card gallery via hyperflow view; the markdown category files remain the on-disk form CRUD operates on.
- compaction.md —
/hyperflow:cache compact protocol: stub format, archive sidecar, idempotency.
- output-style.md — label and table conventions.
- runtime-contract.md —
structured_question, spawn/inline, honest metrics.
- DOCTRINE.md — orchestration rules.
