Memory Stores

Memory Stores hold named files that survive individual sessions. Attach a store to a Claude-compatible session and the agent accesses it under /mnt/memory/<store_name>/ with bash, read, write, edit, glob, and grep. There are no special memory_* tools or required vector-search operations.

Create and attach a store

Use the base URL and key from the REST API guide. Memory endpoints require agent-memory-2026-07-22; session attachment requires managed-agents-2026-04-01. The example sends both beta flags:

MEMORY_BETAS="agent-memory-2026-07-22,managed-agents-2026-04-01"
STORE_ID=$(curl -fsS "$OMA_BASE_URL/v1/memory_stores" \
  -H "x-api-key: $OMA_API_KEY" -H "Content-Type: application/json" \
  -H "anthropic-beta: $MEMORY_BETAS" \
  -d '{"name":"project-notes","description":"Shared project knowledge"}' | jq -r .id)

curl -fsS "$OMA_BASE_URL/v1/memory_stores/$STORE_ID/memories" \
  -H "x-api-key: $OMA_API_KEY" -H "Content-Type: application/json" \
  -H "anthropic-beta: $MEMORY_BETAS" \
  -d '{"path":"/conventions.md","content":"Run the project checks before handing off changes."}'

SESSION_ID="session_..." # Existing Claude-compatible session
curl -fsS "$OMA_BASE_URL/v1/sessions/$SESSION_ID/resources" \
  -H "x-api-key: $OMA_API_KEY" -H "Content-Type: application/json" \
  -H "anthropic-beta: $MEMORY_BETAS" \
  -d "{\"type\":\"memory_store\",\"memory_store_id\":\"$STORE_ID\",\"access\":\"read_only\",\"instructions\":\"Read the project conventions before starting.\"}"

The attached resource’s store name determines the mount directory. Instructions explain how the agent should use the files. Read-only attachment is useful for shared guidance that sessions should consume without changing it.

Access and runtime support

Path	Current behavior
Memory REST API	Create, retrieve, update, delete, and inspect versions within the authenticated workspace
Cloudflare managed sessions	Materialize attached memory and synchronize writable mounts back through the control plane
Node managed-session runner	Read-only mounts when the selected sandbox supports them; rejects read-write mounts until reverse synchronization is configured
OpenAI adapter	Memory attachment is not part of this guide’s /v1 contract; do not assume native resource settings map to OpenAI environment configuration

On a runtime that supports write-back, attach with access: "read_write" to let agent file edits persist. A writable directory alone is insufficient: the runtime must synchronize changes back to the store. Check Managed Runtime Host for the selected deployment’s resource capabilities.

Cloudflare stores memory bytes in R2 and the index / audit in D1. Managed runtime synchronization writes changes through the control plane; R2 Event Notifications also update the index through a Queue consumer. This is distinct from workspace checkpointing, which restores a session’s working directory.

Concurrent edits

The managed synchronizer compares the sandbox workspace with its baseline and the current store. If both sides changed the same path, it reports a conflict instead of silently overwriting the newer content. Treat memory write-back as a separate persistence boundary when inspecting a completed session.

For REST writes, use a content precondition to reject stale updates:

{
  "content": "Updated conventions",
  "precondition": {
    "type": "content_sha256",
    "content_sha256": "<hash-from-current-memory>"
  }
}

The current public create request accepts path and content; it does not accept a precondition field. Apply the hash precondition on updates.

Versions and rollback

Each mutation creates a version record. Memory content is capped at 100 KB; versions have 30-day retention with the most recent version per memory preserved. To roll back, retrieve the desired version and write its content as a new revision. Redacting an older version clears its content while retaining the audit record; the live head cannot be redacted until a newer version exists.

oma memory stores create "Project Notes"
oma memory write <store-id> /conventions.md --from-file conventions.md
oma memory ls <store-id> --prefix /
oma memory versions <store-id> --memory-id <memory-id>
oma memory redact <store-id> <version-id>

Note

Session deletion and Memory Store lifecycle are separate. Stores can be shared by multiple sessions; manage their retention deliberately through the Console or Memory Store API.

See the API reference for memory and version endpoints, and Sandbox & persistence for the distinction between memory, workspace checkpoints, and output files.