Memory

A naive agent dumps every past message into the next context, which burns tokens, blows through the context window, and degrades quality. Memory avoids this by storing curated records and loading only the subject list at the start of a session — full bodies are fetched on demand when the agent decides a record is relevant. This is progressive disclosure: shallow by default, deep when asked.

The win is that a session starts with a tight context footprint regardless of how many past sessions wrote memory, and the agent pulls in depth only for topics that matter to the current turn.

A memory record passes through four states driven by explicit tool calls. The agent is not a passive observer — it decides when to write, update, promote, and forget.

• Draft — created in-session via memory_add. Tagged to the current session, not yet promoted.
• Confirmed — promoted via memory_promote after corroboration. Visible to future sessions.
• Updated — edited via memory_update when new information contradicts or refines the existing record. Prior versions are kept for audit.
• Forgotten — removed via memory_forget when the record is wrong, obsolete, or the user asks to delete it.

Retrieval uses memory_search (find by subject or kind), memory_read (fetch a full body), and memory_expand_section (drill into a nested field). The three read tools form the progressive disclosure ladder.

Configure memory in Settings → Memory or preferences/memory.json. The settings surface controls recall policy, write and promotion rules, progressive disclosure depth, re-ranking, and diagnostics. Presets exist for common profiles (strict, balanced, aggressive).

If you are enabling memory for the first time, use the balanced preset. It writes conservatively (promotions require at least one update), reads subject-only on session start, and expands bodies on demand. Switch to aggressive only after you see the agent miss records it should have remembered.