Concepts
The terms Agent Memory uses, each with a single meaning used throughout the docs.
This page defines the names Agent Memory uses, each with one meaning. The other pages use these names in exactly this sense.
Hierarchy
Tenant (organization)
└── Workspace (project)
├── Shared pool (applicationId = null)
└── Application
└── Run (task / session, runId)| Concept | What it does | Where it comes from |
|---|---|---|
| Tenant | The organization boundary. One tenant's data is never visible to another by any path. | From the credential (API key, session, token). It is not sent in the request. |
| Workspace | A project. The main scope of memory; almost every request carries a workspaceId. Shown as "project" in the console. | The request body/query or the MCP address. An API key is bound to a single workspace. |
| Application | Application-specific memory within the same workspace. Records without an applicationId go to the workspace's shared pool and are visible to all applications. | applicationId, an application-bound API key, or the /v1/mcp/<application-name> address. |
| Run | The ID of a task/session (runId). Groups the records from the same task; consolidation and outcome reporting work per run. | You provide it (^[A-Za-z0-9._-]{1,128}$). It is not an access control. |
Identities
| Concept | Meaning |
|---|---|
Agent (agentId) | The agent that writes or reads memory. You normally do not send it: the agent your API key is bound to performs the operation. If the key is bound to more than one agent, you state which one you are acting as; a name the key is not bound to returns 403. |
End user (userId) | The person the memory is about (for example, the customer an assistant talks to). Not an agent. To send a userId, the key needs the "act on behalf of users" permission (canActForUsers / act for users in the console). |
| Actor | The identity that actually performs the operation (apikey:<id>, a console user). The server records it for auditing. |
Memory structures
| Structure | What it stores | How it is created |
|---|---|---|
| Memory entry | A single piece of information: type, content, tags, visibility, classification, source, timestamps. | add_memory / POST /v1/memory/append, or consolidation. |
| Episode | The record of a run: events, summary, success score. | consolidate(runId), or automatic consolidation of idle runs. |
| Procedure | A "how to" learned from successful repetitions: trigger, goal, steps, things to avoid, confidence. | Consolidation and outcome reporting. |
| Memory block | A manually maintained, labeled text pinned to every context (for example tech_stack). | PUT /v1/blocks/{ws}, curate_block. |
| User profile | A single text profile for an end user. | PUT /v1/memory/users/{ws}/{userId}/profile; optional automatic enrichment. |
| Tenant convention / floor | An admin-approved, tenant-wide rule derived from a decision or approved pattern that recurs across multiple projects. Those approved as a "floor" are included in every context. | Automatic candidate + admin approval. |
Memory types (type)
| Type | When |
|---|---|
decision | An architecture/design decision and its rationale. |
correction | The user corrected the agent; the corrected behavior. |
violation | A rule or constraint was broken. |
approved_pattern | A solution the user accepted, to be reused. |
artifact_ref | A pointer to an important file/resource. Not returned by semantic search; read it by ID (get_memory). |
preference | A person's preference. |
raw | Raw text (for example a conversation line). Split into facts during consolidation. |
Any other type is rejected with 400.
Layer (layer)
| Layer | Where it lives |
|---|---|
Working, Session | Only in the run layer in Redis (48 hours). Consolidation is needed to make them persistent. |
Workspace | Persistent PostgreSQL memory. Searchable as soon as it is written. |
Platform | Platform-wide rules, managed by admins. |
MCP add_memory always writes to the Workspace layer. In REST, always send the layer field: if omitted, Working is assumed and the record does not persist.
Visibility (visibility)
| Value | Who can see it |
|---|---|
workspace (default) | Anyone with access to the workspace. |
private | Only the agent that wrote it. |
agent | The agent that owns the record. |
user | Only calls reading on behalf of that userId. |
tenant | Everyone in the workspace; it does not carry over to other workspaces (see Identity and access). |
Visibility is applied on every search before ranking. Details: Identity and access.
Receipts
- Operation (
operationId): the intake receipt for an append. Shows which ID the record resolved to (new or merged) and the status of follow-up work (embedding, event notification). - Receipt (
receiptId): the receipt for the records each search delivered. Outcomes and feedback are sent with this receipt and the samerunId.