swarm-zap/memory/README.md

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

• projects.md

  • Human-readable registry of active bigger-picture efforts
  • Good for quick orientation across sessions

• tasks.json

  • Structured task state for follow-up and reminders

• tasks.md

  • Human-readable guide for how task tracking should work

• 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. if it's a durable fact, promote it into ../MEMORY.md
3. if it's a bigger ongoing effort, add/update projects.md
4. if it needs follow-up or status tracking, add/update tasks.json
5. only create a named note when the topic genuinely needs a long-lived home

Create a named note when:

• the topic will span multiple sessions
• it needs to collect evidence, commands, or findings over time
• it is likely to be reused as a reference later

Prefer the daily note when:

• it was a one-off conversation
• it was a tiny fix or validation
• the note would otherwise become a small orphan file

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