swarm-memory

Swarm memory

Memory is only useful if it is read before deciding and written after learning. A store that is written but never searched is a diary; one that is searched but never corrected repeats its mistakes forever.

When to activate

• START of any non-trivial task, in the same parallel block as the first reads and before the context pack and contract. A trivial single-file edit skips memory.
• END of any task that produced a decision, a gotcha, or a reusable approach.
• When a past decision is being revisited ("why is it done this way?").

Procedure

1. Recall first. memory_search with 2-4 concrete keywords from the task (component names, error text, feature nouns). Optional type filter: decision, pattern, lesson, event, task.
   • Results exist → use them, and say which memory informed the plan.
   • Nothing → say nothing and proceed. Never invent a recalled memory.
2. Store at the end, one entry. memory_store with the right type:
   • decision — a choice made and why (the alternative rejected matters more than the choice).
   • lesson — a gotcha hit and how it was resolved. This is the highest-value type.
   • pattern — a reusable approach with the file that demonstrates it.
   • event — something that happened (a deploy, a migration, an incident).
3. Correct, do not accumulate. A wrong or outdated memory gets memory_forget with its id, then a corrected entry. Leaving both means the next session gets contradictory advice with no way to pick.

What makes an entry worth keeping

Good: one dense line, searchable nouns, an anchor.

decision: state lives in <project>/.graphyloop/state.json (was .opencode/graphyloop) — three of four harnesses are not opencode; migration in lib/engine.mjs
lesson: node --test hangs when a failing assert skips stdin.end() on a spawned server — the child holds the stdio pipes; close it in a finally
pattern: file-to-file credential sync (env_sync) keeps values out of the model context — see lib/secrets.mjs