agentsclimarketplace
Sign in

Memory flywheel

Skill jajupmochi/agent-harness/skills/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.From its SKILL.md

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.

2 things 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.
  • runs commandsInstructs the agent to run 3 commands, including `python3 scripts/mem.py record --project P --kind design --title "…" --keywords a,b < body` and 2 more.

SKILL.md

3.3 KB, 751 tokens by cl100k_base, 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)

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

What ships with it: 8 files

42.5 KB alongside SKILL.md, 6 of them executable

scripts/

Gives 0 of the 12 instructions most memory context skills give in 751 tokens

Counted across 754 of the 1,056 authors here whose files we hold, read 2026-09-06

  • Preserve existing content structurein 15 of 754, across 9 files
  • Front-load the leading wordin 14 of 754, across 10 files
  • Update existing entries instead of duplicatingin 14 of 754, across 7 files
  • Keep CLAUDE.md under one hundred linesin 14 of 754, across 12 files
  • Read CLAUDE.md at the project rootin 14 of 754
  • Keep each meaning in a single source of truthin 12 of 754, across 8 files
  • Redact sensitive information before committingin 11 of 754, across 4 files
  • Scan for all CLAUDE.md filesin 11 of 754, across 7 files
  • Use frontmatter for metadata on filesin 10 of 754, across 3 files
  • Repeat user interactions 10 timesin 10 of 754, across 4 files
  • Write the CLAUDE.md file into the target folderin 10 of 754, across 8 files
  • Use memlab to process snapshotsin 9 of 754, across 3 files

Said here and by no other author read

  • record the round verbatim
  • recall before acting progressively

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.