Memory model

Agent Needle separates memory by purpose so agents can retrieve narrowly and update the right kind of record.

Active memory

.memory/ACTIVE.md is the handoff note for unfinished work. It should answer one question: what does the next session need to resume safely?

Keep it short. When a task closes, remove it after consolidating durable facts, decisions, and useful episode context.

Episodic memory

Episodes record meaningful events in .memory/episodes/YYYY-MM-DD.md:

• Actions and checks performed
• Results and failures
• Remedies attempted
• Decisions made
• Unresolved threads

Episodes are append-only. Correct an earlier entry with a new note rather than rewriting the historical record.

Semantic state

Files under .memory/state/ hold current verified facts: architecture, commands, integrations, environment constraints, or conventions. Include when the fact was observed and its source when useful.

Semantic state is not a scrapbook. Update it when reality changes and do not preserve obsolete facts as current truth.

Decisions

.memory/decisions/ stores consequential choices with context, alternatives, rationale, consequences, date, and status. Supersede an old decision explicitly instead of erasing its history.

The lifecycle

Request → retrieve relevant context → verify against reality → execute
   ↑                                                   ↓
resume ← active work ← consolidate durable memory ← checkpoint

The agent retrieves by relevance first and recency second. This avoids loading a transcript-sized history into every task.