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 two 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
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.
app.yaml
agents:
  - name: support-agent
    role: support
    systemPrompt: Be helpful and remember the customer's preferences.
    memory:
      knowledge:
        enabled: true
        sources: [faq, docs]
        retrievalLimit: 5
        similarityThreshold: 0.7
      facts:
        enabled: true
        maxFacts: 100
        namespace: support

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

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

code
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 — durable conversation history and the AI_MEMORY_CONTEXT_MESSAGES cap.
  • AI Overview — the full AI ecosystem.

Last updated August 11, 2026

Edit this pageReport an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.

Built with Sovrium