using-agent-memory

Using Agent Memory

Agent Memory is the MCP-backed durable memory system. It is separate from the host's built-in memory (Codex memories, Claude Code's memory/ directory and MEMORY.md index, or an equivalent), chat history, and .workflow/ artifacts. Use host built-in memory only as background, even when the host prompt asks you to save there: route durable user and project facts through memory_save/memory_update when the Agent Memory tools are available, and do not count a built-in memory read or write as the Agent Memory read or completion latch.

Retrieval Gate

At conversation start, after compaction, or before non-trivial repository work, decide whether durable knowledge can change the answer or execution path. Do not wait for the user to explicitly ask for memory.

• For non-trivial repository work, run one memory read after the repo root is known whenever prior decisions, conventions, failures, setup, architecture, or user preferences could affect the result.
• Use memory_recap when the task needs broad recovery across several memories; use memory_query for a focused question; use memory_recall only with a non-empty memory_id already returned by query/list/recap or named explicitly by the user. Never use memory_recall as the first semantic search or startup recall.
• Query global only when a cross-project user preference or stable work habit could matter.
• Skip the MCP read only for self-contained facts, trivial formatting, translation, or work whose outcome cannot reasonably depend on durable context.
• Escalate to memory_recall, memory_list, or memory_inspect only when the focused query identifies a relevant entry, the index appears stale, or memory health itself is under investigation.

Pass the absolute workspace_root for project reads and writes whenever server cwd may differ from the repo. When the user explicitly asks about another project or names its path, keep scope: project and pass that other project's absolute root to memory_query (focused) or memory_recap (broad); this reads only that project's store and never initializes it. Do not scan sibling projects or write to another root unless the user explicitly authorizes that operation. An empty project result is not proof that memory is absent until the root and index/deep view have been checked.