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, "show memory", "search memory for X", "clear memory", "what does hyperflow remember about Y".
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, "show memory", "search memory for X", "clear memory", "what does hyperflow remember about Y".
CRUD interface for .hyperflow/memory/. Full protocol: memory-system.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 ~/.claude/hyperflow-memory.md
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.
add <category> <title>
Categories: learningdecisionpitfallpatternconvention
Prompt via AskUserQuestion for: what, why it matters, tags (controlled vocab).
Append to the matching file using:
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 scripts/memory-index.py .hyperflow.
edit <entry-id>
Locate by date+title slug. Show current value, prompt for new value, update in place.
Remove entries whose referenced files no longer exist (test -f)
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
Confirm via AskUserQuestion: "This wipes all memory for this project. Are you sure?"
If yes → move all content to .hyperflow/memory/archive/cleared-<timestamp>.md, then reset files to empty stubs.
stats
Print: total entries, hot/warm/cold counts, tag frequency table, oldest and newest entry dates.
migrate
Read ~/.claude/hyperflow-memory.md, filter entries matching current project path.
Append matching entries to learnings.md. Leave legacy file untouched.
Print count of migrated entries.
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.
The Compaction Writer is dispatched in a single batch with all eligible entries.
The Stub formatter renders each replacement line as ### [YYYY-MM-DD] Short title [domain, type] — summarized, see archive/YYYY-MM.md.
The Dedup Reviewer performs source-side stub-line match and archive-side header match (date + title + tags on both sides) to prevent duplicates.
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.
The compact subcommand handler refreshes .hyperflow/memory/.checksums (a memory-scoped sidecar — distinct from .hyperflow/.checksums which the scaffold staleness check owns) and exits with 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
Print structured result with counts/changes summary
Overview
/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. 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 migrate only: read access to ~/.claude/hyperflow-memory.md (legacy global memory).
off — single-line Memory writes disabled for this session.
Error Handling
Failure
Behavior
.hyperflow/memory/ missing
Auto-create skeleton (index.md + 5 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 without confirmation (headless)
Refuse and print clear requires interactive confirmation. Do not wipe.
migrate source file missing
Print (nothing to migrate — ~/.claude/hyperflow-memory.md not found) and stop.
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)
