How do I install the Memory Flywheel skill?

Run npx skillmds@latest add jajupmochi/memory-flywheel in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Memory Flywheel safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Memory Flywheel?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Memory Flywheel free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Memory Flywheel?

jajupmochi (@jajupmochi) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Memory Flywheel by jajupmochi — Agent Skill

Name: Memory Flywheel
Author: jajupmochi

Memory Flywheel

Use to persist and recall per-project cross-session working memory so long or multi-project sessions don't lose detail to context compaction. Record each round of progress (verbatim I/O + reasoning + metadata) into a project memory dir, read a coarse INDEX first, then open only what keyword recall points at. Deterministic, grep-native, LLM-as-component.

jajupmochi a44bab0 9 files · 45.8 KB Updated Sep 17, 2026

File contents

memory-flywheel

A per-project, cross-session memory built as an iterating data flywheel (WS-B; overhaul tasks 3/4/5). It complements the raw JSONL logs and the compaction-summary memory: JSONL is too bulky to load whole, and /compact is lossy (it keeps file states + decisions but drops intermediate reasoning and rejected approaches — verified). The flywheel keeps the verbatim detail in grep-native files with a coarse→fine index, so nothing important is silently lost and recall is cheap.

Design (see docs/strategy/agent-harness-overhaul-2026-07-09/00-research.md §B): integrative of Zep's episodic→semantic tiers, MemWalker's descend-a-summary-tree, A-MEM's keyword/graph overlay, and Anthropic's memory-tool + Skills progressive disclosure. The novel niche is a coding-agent, per-project, grep-native file memory combining verbatim leaves + control metadata + a descended coarse→fine index + keyword recall.

Layout (under `--root`, default `.agent-memory/`)

<root>/<project>/
    rounds/NNNN-<kind>.md   one file per round: frontmatter (id, kind, title, ts, keywords) + VERBATIM body
    INDEX.md                coarse layer — a table of every round; READ THIS FIRST

The loop (each substantive round)

Record the round verbatim (raw input/output/decision), tagged with a kind + keywords: python3 scripts/mem.py record --project P --kind design --title "…" --keywords a,b < body (auto-refreshes INDEX.md.)
Recall before acting, progressively — never load everything:
- read INDEX.md (coarse), then
- python3 scripts/mem.py recall --project P --query "terms" → ranked round files; open only those.
- or plain grep -ri terms <root>/P/rounds/ (it's just files).
The store grows and recall improves as you use it — the flywheel.

Why LLM-as-component

record / index / recall are pure deterministic code (no model call). The model only writes the round content and reads what recall returns. This keeps memory cheap, reproducible, and front-end-inspectable.

Status

Extra recall knobs: recall --fuzzy matches similar/variant keywords (memory↔memories); link --from A --to B records a graph edge and recall --graph pulls in rounds linked to a keyword hit (1 hop) so related context surfaces without a shared keyword.

Evaluation: scripts/mem_eval.py --fixtures f.json runs recall over a synthetic corpus + gold-labelled queries and reports recall@k (see eval-fixtures.example.json). Plug real sessions + gold labels into the same JSON to measure on live data. Deterministic; tested (test_mem_eval.py, 3/3).

v0.3 (record / index / recall + --fuzzy + link & --graph overlay + runnable eval harness), tested (test_mem.py 9/9, test_mem_eval.py 3/3). Planned: a supervising hook that reminds the agent to record, and extending the eval harness with the lossiness-delta / descent-efficiency / flywheel-gain metrics from the paper.

---name: memory-flywheeldescription: Use to persist and recall per-project cross-session working memory so long or multi-project sessions don't lose detail to context compaction. Record each round of progress (verbatim I/O + reasoning + metadata) into a project memory dir, read a coarse INDEX first, then open only what keyword recall points at. Deterministic, grep-native, LLM-as-component.---# memory-flywheelA per-project, cross-session memory built as an iterating **data flywheel** (WS-B; overhaul tasks 3/4/5).It complements the raw JSONL logs and the compaction-summary memory: JSONL is too bulky to load whole,and `/compact` is **lossy** (it keeps file states + decisions but drops intermediate reasoning and rejectedapproaches — verified). The flywheel keeps the **verbatim** detail in grep-native files with a coarse→fineindex, so nothing important is silently lost and recall is cheap.**Design (see `docs/strategy/agent-harness-overhaul-2026-07-09/00-research.md` §B):** integrative of Zep'sepisodic→semantic tiers, MemWalker's descend-a-summary-tree, A-MEM's keyword/graph overlay, and Anthropic'smemory-tool + Skills progressive disclosure. The novel niche is a *coding-agent, per-project, grep-native file*memory combining verbatim leaves + control metadata + a descended coarse→fine index + keyword recall.## Layout (under `--root`, default `.agent-memory/`)```<root>/<project>/ rounds/NNNN-<kind>.md one file per round: frontmatter (id, kind, title, ts, keywords) + VERBATIM body INDEX.md coarse layer — a table of every round; READ THIS FIRST```## The loop (each substantive round)1. **Record** the round verbatim (raw input/output/decision), tagged with a kind + keywords: `python3 scripts/mem.py record --project P --kind design --title "…" --keywords a,b < body` (auto-refreshes `INDEX.md`.)2. **Recall** before acting, progressively — never load everything: - read `INDEX.md` (coarse), then - `python3 scripts/mem.py recall --project P --query "terms"` → ranked round files; open only those. - or plain `grep -ri terms <root>/P/rounds/` (it's just files).3. The store grows and recall improves as you use it — the flywheel.## Why LLM-as-componentrecord / index / recall are pure deterministic code (no model call). The model only *writes the round content*and *reads what recall returns*. This keeps memory cheap, reproducible, and front-end-inspectable.## StatusExtra recall knobs: `recall --fuzzy` matches similar/variant keywords (memory↔memories); `link --from A --to B`records a graph edge and `recall --graph` pulls in rounds linked to a keyword hit (1 hop) so related contextsurfaces without a shared keyword.**Evaluation:** `scripts/mem_eval.py --fixtures f.json` runs recall over a synthetic corpus + gold-labelledqueries and reports recall@k (see `eval-fixtures.example.json`). Plug real sessions + gold labels into the sameJSON to measure on live data. Deterministic; tested (`test_mem_eval.py`, 3/3).v0.3 (record / index / recall + `--fuzzy` + `link` & `--graph` overlay + runnable eval harness), tested(`test_mem.py` 9/9, `test_mem_eval.py` 3/3). Planned: a supervising hook that reminds the agent to record, andextending the eval harness with the lossiness-delta / descent-efficiency / flywheel-gain metrics from the paper.

Frequently asked questions