Agent memory

A memory store in Orca Agent Engine is a named, Workspace-scoped container for agent memories. Unlike a Session, which lives for the duration of one conversation, a memory store persists across sessions: an agent attaches the store as a resource, then reads and writes it as a directory so it can carry context, notes, and learned facts from one run to the next. A store is created once and referenced by ID from any number of sessions.

Get your registry endpoint

Memory store configuration fields

The memory store resource exposes the fields below. Field names use snake_case over the wire.

The response from any memory store endpoint also includes server-managed fields: id, type (always memory_store), created_at, updated_at, and (for archived stores) archived_at.

Create a memory store

Create a store with ork agent memory-stores create, the TypeScript SDK, or a POST to /v1/memory_stores.

store=$(ork agent memory-stores create \
  --name "support-triage-memory" \
  --description "Carries triage context across support sessions" \
  --metadata team=support \
  -o json)

STORE_ID=$(jq -r '.id' <<< "$store")

A successful create returns 200 OK with the new store:

{
  "id": "mems_01H8...",
  "type": "memory_store",
  "name": "support-triage-memory",
  "description": "Carries triage context across support sessions",
  "metadata": { "team": "support" },
  "created_at": "2026-05-11T17:24:08Z",
  "updated_at": "2026-05-11T17:24:08Z"
}

Capture the id - it's how you attach the store to a session.

Attach a memory store to a session

A memory store does nothing until an agent mounts it. Add it to a session's resources array with type: "memory_store", the memory_store_id from create, and an access mode - read_only or read_write - that controls whether the agent can write back. The ork CLI accepts the hyphenated memory-store spelling and converts it to memory_store on the wire.

$SESSION_ID and sessionId are the id of an existing session - see Create a session.

ork agent sessions resources add \
  --session "$SESSION_ID" \
  --type memory-store \
  --memory-store-id "$STORE_ID" \
  --access read_write \
  --instructions "Record durable facts about this customer here."

The runtime mounts the store inside the session's container as a directory. The agent reads existing memories at the start of a turn and writes new ones back when access permits. The instructions field is stored and returned but never reaches the agent - nothing in the harness reads it. To tell the agent what belongs in the store, put it in the agent's system prompt or a user.message.

mount_path is derived by the registry rather than chosen by you. It is /mnt/memory/<store-name>/, falling back to the store ID when the name is not a safe path segment, so the store's name is what decides the directory. A memory-store resource body takes type, memory_store_id, access, and instructions and nothing else: sending mount_path when you attach the store returns 400, and sending it to update an attached resource returns 400 memory_store mount_path is output-only and cannot be updated. The derived path is returned on the resource so you can read it back. A session can mount at most 8 memory stores. You can also mount a store at session-creation time by including the same entry in the session's resources array; see Sessions.

Manage memory stores

Retrieve a store

ork agent memory-stores get $STORE_ID

List stores

ork agent memory-stores list

List accepts limit, page, include_archived, and the created_at[gte] / created_at[lte] range filters. Pass include_archived=true to surface archived stores.

Update a store

Update uses POST on the store path with partial-update semantics: fields you omit are left unchanged. Set a metadata key to null to remove it.

ork agent memory-stores update $STORE_ID \
  --description "Triage memory (prod)"

Archive or delete

Archive sets archived_at, hides a store from default list results, and preserves its contents. It blocks memory writes and prevents a later runtime setup from mounting the store. An already-mounted sandbox is not torn down by the archive, but a session that must prepare the archived resource again fails setup. Do not archive a store while sessions still need to restart with it mounted. Delete removes the store permanently and returns a tombstone; sessions that reference a deleted store surface an error on next read.

# Archive
ork agent memory-stores archive $STORE_ID

# Delete
ork agent memory-stores delete $STORE_ID

Audit and redact memory versions

Every write an agent makes to a memory produces a memory version. Versions are the audit trail for a store: they record what changed, who changed it, and when. Use them to answer "what did this agent write, and when did it write it," and to remove content that should never have been persisted.

A memory version carries these fields:

List versions

versions=$(ork agent memory-versions list --memory-store "$STORE_ID" -o json)

# The examples below act on one version, so keep the newest.
VERSION_ID=$(jq -r '.data[0].id' <<< "$versions")

Narrow the list with these query parameters:

Retrieve a version

ork agent memory-versions get $VERSION_ID --memory-store $STORE_ID

Redact a version

Redaction destroys a version's content. Use it when an agent persisted something that must not be retained - a customer secret, personal data, a leaked token.

ork agent memory-versions redact $VERSION_ID --memory-store $STORE_ID

The response is the redacted version. content, content_sha256, content_size_bytes, and path all become null, and redacted_at and redacted_by are stamped with the time and the actor that ran the redaction. The version record itself stays in the audit trail.

Permissions

Treat every Workspace API key as full access to its Workspace's resources, and separate access with Workspaces. See Control registry access.

What's next