Skip to content

Memory#

Managed agents have a two-layer memory system: a searchable database for detailed entries, and a curated summary that is always loaded into the agent's context.

Two-Layer Architecture#

Memory database#

A persistent, searchable store of individual memory entries. The database grows as the agent learns — there is no hard limit on the number of entries.

Each entry contains:

Field Description
Content Free-text information to remember
Category One of: observation, action, decision, event
Importance Score from 1 to 10 (default 5). Higher-importance entries surface first in search results
Timestamp When the entry was created

Importance guidelines:

Score Use for Example
1–2 Transient observations "Checked pod status, all healthy"
3–4 Context worth keeping short-term "User prefers YAML over JSON for configs"
5–6 Standard operational knowledge "Production cluster runs on EKS in us-east-1"
7–8 Important decisions and events "Migrated from Deployment to StatefulSet for the database"
9–10 Critical knowledge "Production DB credentials rotate every 90 days via Vault"

Memory summary#

A curated markdown file that is always loaded into the agent's context on every invocation. This is the agent's "cheat sheet" — the most critical knowledge distilled into a concise document.

The memory summary is one of the seven workspace files. The agent manages it primarily, but you can edit it directly in the workspace editor.

The default template includes sections for:

  • Important Decisions
  • Known Issues
  • Entity Knowledge
  • Patterns

Keep the memory summary concise. Everything in it consumes context tokens on every invocation. Use the memory database for detailed records and the summary for the essentials.

Search capabilities#

Agents search the memory database using the memory_search tool:

  • Full-text search — case-insensitive text matching across all entries
  • Category filter — restrict results to specific categories (e.g., only decision entries)
  • Time range — filter by recency using a daysBack parameter (default: 30 days)
  • Wildcard queries — use *, all, or an empty string to return all memories
  • Result ordering — sorted by importance (descending), then by recency

Example: an agent investigating a deployment failure might search for deployment rollback filtered to action and decision categories to recall how similar situations were handled before.

Retention policy#

Low-importance entries are automatically cleaned up:

  • Entries with importance below 3 that are older than 30 days are deleted
  • Entries with importance 3 or above are retained indefinitely
  • The memory summary is never affected by retention — it persists until manually edited

This keeps the database focused on knowledge that matters while allowing transient observations to expire naturally.

Channel learning queue#

When a managed agent participates in a Slack channel in team mode, messages not directly addressed to the agent are queued for passive learning. The queue processes messages in batches (up to 10 messages, max 5 minutes old), grouped by channel. This allows agents to absorb team context over time without requiring explicit interaction.

How Agents Use Memory#

Agents manage their own memory through three tools:

Tool Purpose
memory_write Store a new entry with content, category, and importance
memory_search Retrieve entries by query, category, time range
memory_delete Remove entries by ID (with optional reason)

The curated memory summary is updated separately via the update_memory tool, which supports both full replacement and targeted edits (passing {oldText, newText} pairs for surgical changes).

Typical memory flow during an investigation:

  1. Agent receives a question about a production incident
  2. Searches memory for related entries (memory_search)
  3. Uses results to inform its investigation
  4. Stores the outcome as a new memory entry (memory_write)
  5. If the finding is critical, updates the memory summary (update_memory)

Best practices#

  • Let the agent manage its own memory. Intervene only when you notice incorrect or missing knowledge.
  • Use importance scores deliberately. Ask the agent to store critical decisions at importance 8–10 so they always surface first.
  • Review the memory summary periodically. It is the most impactful file for agent behavior since it is always in context.
  • Use the database for volume, the summary for essentials. A 200-line memory summary slows the agent down; a 10-line summary with the right information makes it sharp.