Memory flywheel

Skill jajupmochi/agent-harness/skills/memory-flywheel

Linlin's curated AI agent harness configuration: workflow rules, skills, hooks, plugin recommendations, tooling preferences, and project templates. Loadable into any new project so a fresh /init can pick the relevant subset.

Install

npx -y skills add jajupmochi/agent-harness --skill memory-flywheel

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

3.3 KB, as published. Nobody here has run it

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.