Agent Memory
Concepts

Scoping

How memory is organized into tenants, workspaces, applications, runs and facets — and what each scope can see.

Every memory has an address. The hierarchy is:

Platform (global, operator-managed)
└── Tenant              your organization
    └── Workspace       a shared memory pool (a "project" in the console)
        └── Application an app-specific slice of the workspace
            └── Run     one task or session (runId)

Tenant

A tenant is an isolated customer organization. Tenant boundaries are enforced in the database with row-level security: a request authenticated for one tenant can never read or write another tenant's rows, and a resource that belongs to another tenant answers 404 rather than revealing that it exists. See Multi-tenancy.

Workspace

A workspace is the unit of shared memory and the unit of access control. API keys are issued for exactly one workspace, and every request names its workspaceId. Everything an agent writes to a workspace is, by default, recallable by every other agent in that workspace.

To isolate agents, use separate workspaces

Agent IDs label who wrote a memory and drive per-memory visibility, but they are not an isolation boundary on their own. If two agents must never see each other's workspace-visible memories, give them separate workspaces — or write with a narrower visibility.

Application

Applications let several apps share one workspace while keeping app-specific memory apart. The rule is additive:

Memory written with…Visible to
no applicationId (workspace-wide)every application in the workspace
applicationId = Aonly requests scoped to application A

An application-scoped request sees its own application's memories plus the workspace-wide pool, never another application's private memories. Write shared conventions (stack, coding style, error format) without an application; write app-specific decisions with one.

You scope a request to an application by:

  • passing applicationId on REST requests,
  • using an API key created for that application in the console, or
  • connecting an MCP client to the per-application URL /v1/mcp/<app-name> (the application is created on first use). See MCP.

Relationship edges are workspace-wide

Supersede and contradiction relationships between memories are tracked at the workspace level, regardless of application.

Run

A run (runId) groups the entries of one task. Use one stable runId for the whole task: it is what consolidation sweeps, what session memory is keyed by, and what receipts, outcomes and feedback are tied to. runId must be 1–128 characters of letters, digits, ., _ and -.

Facets

A facet is an optional, cross-cutting label inside a workspace or application — for example a feature area like auth or payments. Facets are stored as the facet tag:

  • Write: add "tags": { "facet": "auth" } (or facet="auth" in the MCP add_memory tool).
  • Recall: pass "tags": { "facet": "auth" } on retrieve (or facet="auth" in search_memory) to narrow the search to that facet.

Facets are advisory: the primary separation is the application, and an agent that forgets to tag a memory will not find it under a facet filter.

What a recall includes

A single recall merges, in priority order:

  1. Memory blocks visible to the agent
  2. The end user's profile (when userId is given)
  3. Platform policies and tenant floors (non-negotiable)
  4. Tenant conventions
  5. Workspace memory (workspace-wide plus the request's application)
  6. Procedures and relevant past episodes
  7. The run's session summary and session entries

See Retrieval for how that context is ranked and fitted to a token budget.

Memory types

Session, workspace, episodic and procedural memory, memory blocks, and the type field that drives the pipeline.

Runs and consolidation

How a run's entries are promoted into durable facts, an episode and procedures — and how facts are promoted further to tenant conventions.

On this page

TenantWorkspaceApplicationRunFacetsWhat a recall includes