/memory-consolidate

name: memory-consolidate
description: Consolidate L1 memory atoms into L2 scene blocks and L3 persona. Invoked by the memory-consolidator agent, or manually via /memory-consolidate.

Memory Consolidation

Analyze L1 atoms and produce L2 scene blocks + L3 persona. You perform all reasoning — no external LLM needed.

Scope boundary (read first)

Consolidation is a **distillation of the memory store's own atoms** — NOT a code audit. Work ONLY from what `tmem consolidate-context` returns (atoms, scenes, persona, changelog). Do **NOT** `grep`, `find`, `cat`, `ls`, `sed`, read repo source/docs, or otherwise explore the filesystem — measured, that "spelunking" is the single largest cost driver of a consolidation run and adds no quality. If the atoms are thin, write less; never go looking in the repo to pad a scene.

Workflow

1. Load the consolidation context — ONE call

tmem consolidate-context     # status + scenes + atoms DELTA + persona + doctrine + changelog, as JSON

This single call replaces the old status / scenes-list / atoms / persona reads. Parse the JSON once:

• `busy: true` — another consolidation already holds this project's store. **Stop

here.** Do not read, fold or write anything; there is no partial work to do and two folds of one store overwrite each other's merges. Report the message and finish.

• `status` — record counts (global + project). If both totals are 0, tell the user

to run memory-seed first and stop.

• `scenes` — existing `{name, summary, heat}`. Reuse an exact name when a topic

matches, so the scene updates in place instead of duplicating.

• `atoms.project` / `atoms.global` — the DELTA since the last consolidation (the

per-project watermark), so the pool you reason over stays bounded no matter how large the store grows. Cold start (no watermark) returns the full pool, correct for the first run. This call also CUTS the window this run may fold: whatever another session captures while you work is deliberately left for the next run, and step 5 credits exactly the window you were handed here — never "everything in the store as of when you finished".

• `persona.global` / `persona.project` — current global persona + project doctrine,

to MERGE into (step 4) — you do not re-read them separately.

• `changelog` — recent writes, for context.

(To force a full re-read of atoms instead of the delta, use `tmem atoms project` with no flag or `--since <iso-timestamp>`.)

2. Verify & dedup atoms before consolidating (close the loop)

Do not consolidate atoms blindly — the measured store was ~40% junk/duplicate and 16% of mined "fixes" were themselves errors. First remove exact duplicates with the hard script:

tmem dedup --atoms --dry-run     # then --apply if the plan looks right

Then, for the remaining atoms, decide per atom against the existing pool (search candidates with `tmem search "<key phrase>"`):

• **store** — genuinely new information → keep.
• **skip** — an existing atom already says it (no increment, or vaguer) → drop.
• **update** — same fact, this atom is more specific/newer/corrects the old → fold

the correction in, keep the union of timestamps, do NOT inflate priority.

• **merge** — same fact/evolution across several atoms → combine into one complete,

non-redundant atom.

Drop a mined error→fix atom whose fix ITSELF errored later in the transcript (flailing) — a wrong fix enshrined as a rule is worse than none. Cross-type merges are allowed (an episodic + a persona describing the same fact → one atom of the better type).

3. Generate L2 scene blocks

Group project-scoped atoms by topic into narrative scenes.

**Important:** If a scene with the same topic already exists (from the `scenes` list in step 1), reuse that exact name so the file gets updated instead of duplicated.

Write ALL scenes in ONE call — pass a JSON array on stdin (this is one tool-call instead of one per scene):

cat <<'SCENES_EOF' | tmem write-scenes
[
  { "name": "Scene Name", "summary": "One-line summary, max 80 chars", "heat": 3,
    "body": "## Key Facts\n- Fact 1\n- Fact 2\n\n## Decisions\n- What was decided and why" },
  { "name": "Another Scene", "summary": "…", "heat": 5, "body": "## Key Facts\n- …" }
]
SCENES_EOF

A reused `name` overwrites in place (no duplicate). `body` defaults to `summary` if omitted. (For a one-off single scene you may still use `tmem write-scene --name … --summary … --heat … < body`, but prefer the batch.)

**Guidelines:**

• Group by topic, not by session
• Aim for 5-15 scenes per project — fewer if topics are narrow, more if diverse
• Heat 4-5: active this week. Heat 2-3: recent but not current. Heat 1: historical. Only heat 5 (two flames) and heat 4 (one flame) get a flame cue in the nav; 1-3 render none, so reserve 4-5 for genuinely current work rather than defaulting there.
• Each scene should be understandable on its own

**How scene-body FACTS are delivered** (the body is a per-turn recall surface now, not just an on-demand read):

Each `- ` bullet under `## Key Facts` and `## Decisions` is indexed and, every turn, ranked against the user's prompt and injected — the top few — into a `<recalled-facts>` block (own budget, ~700 chars, project scenes first). This is the PRIMARY per-turn memory: raw L1 episodic atoms are no longer recalled (they were measured to echo the current turn, 1/10 helpful), so a fact reaches a future agent ONLY if it is a scene-body bullet here. Measured: distilling facts into this block lifted real-query helpfulness from 1/10 to 5/10.

So write each bullet as a **self-contained answering fact that carries the outcome**, not a topic label:

• **Stand alone.** A bullet is recalled without its scene around it. "Fixed the

launcher bug" is useless out of context; "tmem.js resolved the plugin-cache cli.js before its own sibling, so `npx @baodq97/tmem` ran stale code — fixed by making the sibling authoritative (v0.7.3)" answers the question by