Memory types

Agent Memory keeps several kinds of memory, each with its own lifetime and purpose. A single recall assembles all of them into one context.

Session memoryCopy Anchor Link

Every write lands in the run's session memory first. Session memory is grouped by runId (1–128 characters: letters, digits, ., _ and -) and expires 48 hours after the last write. When a run's buffer grows long, older entries are compressed into a session summary so the context stays small.

Session entries come back in recall under sessionEntries (and sessionSummary) for the same runId.

Workspace memoryCopy Anchor Link

Workspace memory is the durable store. Each memory carries:

• a type (see below) and free-form tags
• an embedding for semantic search, plus full-text indexing
• provenance — sourceKind, sourceRef, how it was extracted, and which episode it came from
• bi-temporal fields — observedAt, validFrom, validTo (when it was true in the world) and recordedAt, supersededAt (when the system knew it)
• policy — visibility, ownerAgentId, classification
• trust inputs — confidence, importance, usage count, learned utility and stability, combined into a read-time trust breakdown
• a version for safe concurrent updates

A memory enters workspace memory in two ways:

1. Directly — an append with layer: "Workspace" is stored durably at once (and also recorded in the run). The SDKs and MCP tools always write this way.
2. By consolidation — at the end of a run, session entries are distilled into canonical facts. See Runs and consolidation.

Near-duplicate writes are merged instead of stored twice (a time-window check, embedding similarity and word overlap). The append response tells you when that happened (merged: true) and returns the surviving memory's ID.

The type fieldCopy Anchor Link

type is required on every write and drives much of the pipeline: what gets promoted into facts, how a run is scored, what becomes a procedure and which memories can contradict each other. The registered types are:

An unknown type is rejected with 400 VALIDATION_FAILED.

Episodic memoryCopy Anchor Link

Consolidating a run creates one episode. Each session entry becomes an episode event, and the episode records the run's goal, outcome (successful, failed or uncertain), a successScore between 0 and 1, and a generated summary. Episodes link to the previous episode, and facts promoted from a run point back to their episode, so you can always ask where a fact came from.

Recall includes the most relevant past episodes under relevantEpisodes. You can also list and search them directly — see Episodes and procedures.

Procedural memoryCopy Anchor Link

Procedures are reusable "how-to" knowledge. They are produced in two ways:

• Within a run — when a consolidated run scores above 0.7 and contains an approved_pattern, its event sequence becomes the procedure's steps.
• Across runs — approved_pattern and decision facts that are confirmed repeatedly with high confidence are generalized into procedures.

Each procedure tracks validations, successes and failures. Applying a procedure and reporting the outcome strengthens or weakens it; failed runs contribute anti-patterns that appear in context as things to avoid.

Memory blocksCopy Anchor Link

Blocks are small, labeled pieces of free text — for example conventions or tech_stack — that are always included at the top of a recalled context. They are structurally separate from everything else: no embeddings, no type, no decay, and consolidation never touches them. Agents or humans maintain them line by line with the add, replace and remove curation actions.

A block can be workspace-wide (agent scope *) or scoped to one agent, and workspace-wide or scoped to one application. Blocks are limited to 2,000 characters by default.

User profilesCopy Anchor Link

A user profile is one document per end user (userId) in a workspace, included in recall when the request names that user. Profiles can be written directly through the API, and a workspace setting can enrich them automatically with preference facts found during consolidation.

Tenant and platform memoryCopy Anchor Link

• Tenant conventions are facts shared by every workspace in a tenant. They are created by promotion: when the same fact is established independently in at least two workspaces, it becomes a candidate that a tenant administrator approves or rejects. Approved conventions appear in recall under tenantEntries.
• Tenant floors are non-negotiable tenant policies, always included in context.
• Platform memory is managed by the platform operator and is visible to all tenants. Policy entries are non-negotiable and rendered before everything except blocks; Default entries are overridable conventions.

How it fits togetherCopy Anchor Link

add memory (during a run)
        │
        ▼
Session memory (per runId, 48h) ──consolidate──► Episode ──► episode events
        │                                           │
        │ layer = Workspace                         ▼
        └────────────────────────────────► Workspace memory (facts)
                                                    │
                                    successful runs, repeated evidence
                                                    ▼
                                               Procedures

Memory blocks ── curated separately, always in context