memory

name	memory
description	Agent Memory system with canonical Memory Notes, derived Memory Views, Dream capture, and explicit note operations.
always	true

Memory

Structure

• memory/notes.jsonl is the canonical Agent Memory store. It contains typed Memory Notes with status, priority, confidence, source trace-back, timestamps, and lifecycle links.
• memory/MEMORY.md is the project Memory View rendered from active project, decision, fix, and followup notes.
• USER.md is the user Memory View rendered from active preference notes.
• SOUL.md is the assistant Memory View rendered from active instruction notes.
• memory/conversations/*.jsonl stores clean Conversation Evidence for completed user/assistant messages. Dream processes it before legacy summary history.
• memory/.evidence_cursor tracks processed Conversation Evidence. memory/history.jsonl and .dream_cursor remain the legacy fallback path.

Explicit Operations

Use Memory Note operations for durable agent-side memory:

• save_memory_note for new durable preferences, instructions, project facts, decisions, fixes, or followups.
• search_memory_notes to find notes by query, type, status, and limit.
• trace_memory_note to inspect note content and source trace-back.
• reject_memory_note to remove a wrong or obsolete note from default recall and Memory Views.
• supersede_memory_note to replace an old note while preserving the lifecycle link.

Boundaries

• Memory Notes are separate from Experience records. Experience captures reusable execution tactics and recovery guidance.
• Memory Notes are separate from Knowledge Base snippets and uploaded session documents. Knowledge is evidence, not durable agent memory.
• Recent Context is separate from Durable Memory Notes. It reads bounded Conversation Evidence for short-term follow-up continuity, exposes recent conversation references, and does not write USER.md or other Memory Views.
• Optional vector indexes may accelerate Memory Note search, but memory/notes.jsonl remains canonical and indexes must be rebuildable from it.

Important

• Do not edit managed sections in SOUL.md, USER.md, or memory/MEMORY.md directly. They are Memory Views refreshed from active Memory Notes.
• If a Memory View looks wrong, use reject or supersede operations on the underlying note instead of editing rendered Markdown.
• Users can view Dream activity with the /dream-log command.
• session.user_profile is only a runtime cache. Durable user facts belong in user-scoped Memory Notes.