swarm-zap/memory

Memory Layout

This folder is the assistant's working memory on disk.

Roles

• ../MEMORY.md

  • Curated long-term memory
  • Durable truths only
  • Examples: preferences, stable decisions, important future dates, recurring lessons

• YYYY-MM-DD.md

  • Daily inbox / timeline
  • Default place for new notes
  • Prefer this over creating a new one-off file

• ops/

  • Operational notes
  • Setup history, routing decisions, workflow changes, tool behavior, validation notes

• incidents/

  • Debugging and incident history
  • Errors, outages, investigations, mitigations, postmortem-style notes

• plans/

  • Multi-session plans or ongoing initiatives

• references/

  • Stable supporting material worth keeping around for reuse

• archive/

  • Old low-value or superseded material kept only for traceability

Retrieval model

Files are the source of truth.

Embeddings are the lookup layer:

• use semantic search to find likely relevant notes
• then read the source lines
• answer from the file, not from the vector hit alone

Writing guidance

When in doubt:

1. write to today's daily note
2. later promote durable truths into ../MEMORY.md
3. only create a named note when the topic genuinely needs a long-lived home

Cleanup guidance

If top-level memory/ starts filling with non-daily files again:

• move operational material to ops/
• move debugging material to incidents/
• move stale low-value chatter to archive/
• keep top-level mostly daily notes