Skip to main content
View as Markdown

AI Memory

Agent memory gives an agent context that persists beyond a single message. It is configured under an agent's memory block and is composed of three independent tiers, each disabled by default and enabled individually. Before the runtime invokes the LLM (for example, when the ai:agent automation action dispatches a task), it assembles context from whichever tiers are enabled.

Tier Persistence Direction Purpose
conversation Session-level (ephemeral, windowed) Read Maintain dialogue context across recent messages.
knowledge Read-only RAG sources Read Retrieve relevant documents via semantic search.
facts Persistent across sessions Read/write Remember AI-managed facts the agent learns over time. 
agents:
  - name: support-agent
    role: support
    systemPrompt: Be helpful and remember the customer's preferences.
    memory:
      conversation:
        enabled: true
        windowSize: 10
        summarize: true
      knowledge:
        enabled: true
        sources: [faq, docs]
        retrievalLimit: 5
        similarityThreshold: 0.7
      facts:
        enabled: true
        maxFacts: 100
        namespace: support

Conversation Memory

Retains recent messages from the agent's session. When enabled, the runtime loads the last windowSize messages into context before each invocation.

Property Default Description
enabled false Whether conversation memory is active.
windowSize 10 Number of recent messages kept in context.
summarize false When true, older messages are compressed into a summary instead of dropped.

Knowledge Memory

RAG-based semantic retrieval from configured knowledge sources. When enabled, the runtime runs a similarity search against the listed sources before each invocation and injects the most relevant documents into context. This is the runtime retrieval side of RAG — distinct from the agent's knowledge block, which defines the input sources that get embedded.

Property Default Description
enabled false Whether knowledge retrieval is active.
sources — Knowledge source names to search (must reference configured knowledge bases).
retrievalLimit 5 Maximum documents retrieved per query.
similarityThreshold 0.7 Minimum similarity score (0–1) for a retrieved document to be included.

Facts Memory

Persistent key-value facts the agent learns across sessions. Unlike the state automation action (explicit developer-set KV), facts are AI-managed: the agent itself decides what is worth remembering. Facts are retrieved by semantic relevance to the current task, not by exact-key lookup.

Property Default Description
enabled false Whether facts memory is active.
maxFacts 100 Maximum number of facts the agent can store.
namespace agent name Namespace for fact isolation. Lowercase, starts with a letter (^[a-z][a-z0-9-]*).

Namespace Isolation & Per-User Scoping

Facts are partitioned by namespace (defaulting to the agent's name), so two agents never read each other's learned facts. Combined with the agent-as-user model — each agent is a distinct auth.user — this gives per-agent and, where chat scopes by session, per-user fact isolation. An agent cannot leak one customer's learned facts into another customer's conversation.

Tier Composition

All three tiers are optional and combine freely. A read-only analyst agent might enable only knowledge; a long-running support agent might enable all three. When multiple tiers are enabled, the runtime assembles context from each before invoking the LLM:

conversation (recent dialogue)
        +
knowledge (semantically-retrieved docs)
        +
facts (relevant learned facts)
        ▼
   assembled context → LLM
  • AI Agents — the agent the memory block belongs to.
  • AI RAG — the embedding/retrieval pipeline knowledge memory uses.
  • AI Chat — conversation history in the chat interface.
  • AI Overview — the full AI ecosystem.