Memory providers

Providers own storage, retrieval and writes. defineMemory declares a resource; useMemory returns its text, sources and writable. Your render chooses how to include the recalled text in the instructions.

Choosing a providerCopy Anchor Link

Hooks stay stable; bindings, tools, prompts and editors may change. Changing provider kind requires a new resource and migration. A new endpoint copies no data: confirm it addresses the existing store or migrate, including sessions pinned to old deployments.

Declare an HTTP providerCopy Anchor Link

The deployment stores configuration; your endpoint executes provider code.

import {
  bearer, defineConnection, defineMemory,
  httpMemory, useSecret,
} from "@opencomputer/agent";

const connection = defineConnection({
  id: "memory-service",
  origin: "https://memory.example.com",
  methods: ["POST"],
  pathPrefix: "/oc-memory",
  headers: {
    Authorization: bearer(useSecret("MEMORY_TOKEN")),
  },
});

export const knowledge = defineMemory({
  id: "knowledge",
  description: "Verified facts needed in later sessions.",
  provider: httpMemory({
    connection,
    path: "/oc-memory",
    maxBytes: 8_192,
    tools: [{
      name: "remember",
      description: "Save a verified fact.",
      access: "write",
      idempotent: false,
      input: {
        type: "object",
        properties: {
          fact: { type: "string", maxLength: 2_000 },
        },
        required: ["fact"],
        additionalProperties: false,
      },
    }],
  }),
});

Namespace and tool selectionCopy Anchor Link

Session memory binding (knowledge and owner are application-defined):

{
  "knowledge": {
    "scope": "namespace",
    "id": "owner",
    "access": "read-write"
  }
}

Fixed tool names use memory_<tool>, here memory_remember.

• Target: optional memory selects an eligible resource from the originating render; required when more than one qualifies. OpenComputer strips it, then validates provider arguments, including additionalProperties: false. The endpoint receives the partition instead.
• Rejection: a wrong target returns rejected / not_bound with eligible targets. Changed access rejects the call; it never redirects it.
• Collisions: identical names merge only with identical schemas, retaining each target’s descriptions, access checks and retry policy. Incompatible schemas or collisions with ordinary tool names reject session creation.

Endpoint protocolCopy Anchor Link

All operations use POST, Content-Type: application/json, version: 1. Authenticate the connection credential, enforce read-only access, reject expired deadlines and prevent arguments selecting another partition.

RecallCopy Anchor Link

Request:

{
  "version": 1,
  "operation": "recall",
  "operationId": "mrq_123:knowledge",
  "partition": "ocmem_v1_opaque-partition",
  "access": "read-write",
  "deadlineAt": "2026-09-10T15:04:15.000Z",
  "input": { "text": "What hosting did we choose?" },
  "maxBytes": 8192
}

Response, HTTP 200:

{
  "text": "No paid external services for the demo.",
  "sources": [{
    "id": "fact:hosting",
    "title": "Hosting constraint"
  }],
  "cursor": "provider-snapshot-42"
}

Recall has no storage side effects. OpenComputer persists the accepted projection before inference and reuses it on request retries. Before acceptance, recall retries may see newer data. New model requests recall again.

No automatic turn-completion or compaction callbacks. Conversation-fed services need a separate ingestion path.

ToolsCopy Anchor Link

Endpoints cannot add tools or widen access beyond deployment declarations. Requests contain validated arguments and the recall cursor, if supplied:

{
  "version": 1,
  "operation": "tool",
  "operationId": "toolcall_456:knowledge",
  "partition": "ocmem_v1_opaque-partition",
  "access": "read-write",
  "deadlineAt": "2026-09-10T15:04:25.000Z",
  "tool": "remember",
  "arguments": {
    "fact": "Use the free hosting tier for the demo."
  },
  "cursor": "provider-snapshot-42"
}

Return HTTP 200; any JSON result reaches the model unchanged:

{ "result": { "status": "stored" } }

Tool descriptions must explain visibility. Providers own write semantics; document-memory revision checks do not apply.

For conflicts, return HTTP 409 with this error envelope (details optional):

{
  "error": {
    "code": "conflict",
    "message": "Knowledge changed; reconcile it.",
    "details": {}
  }
}

All errors use this envelope and reach the model without advancing the cursor. Tools from one response share it; the next request recalls again.

Deadlines and retriesCopy Anchor Link

idempotent: true requires deduplication by (partition, operationId), rejection of changed tools/arguments/cursors, and replay of the original result until deadlineAt. An adapter cannot guarantee this over an upstream service that may commit a write before losing its reply.

With idempotent: false, transport failures and timeouts return { "status": "uncertain" } without retry. The next request recalls current state; timeout does not prove failure.

Invalid JSON, oversized output, authentication failures and exhausted retries produce visible errors. Failed recall blocks inference, never substituting empty memory. Tool errors imply no rollback. Anything placed in instructions consumes model context.

Lifecycle and owner controlsCopy Anchor Link

• Access: OpenComputer checks bindings before each call. Session end blocks new calls after revocation; earlier calls may still commit remotely.
• Cancellation: aborts the request, without undoing accepted writes. Stronger fencing belongs in the provider’s storage protocol.
• Ownership: the provider supplies retention, backups, inspection, export and deletion. OpenComputer document editing/freezing applies only to documentMemory; deleting a project does not delete remote data.
• Inspection: the resource inventory identifies each resource’s provider. Session inspection would expose namespace and partition so owners can locate remote data.