Memory API

Core CRUD, search, version history, and rollback endpoints for tenant memories.

Use this when your application needs to store, query, or revise tenant-scoped memory records.

Endpoints

Available endpoints

GET

/memories

Lists memories with filter and pagination support. Query params: q, type, sensitivity, status, contradiction, namespace, from, to, limit, offset.

API key

List memories

The list endpoint supports filters and pagination.

curl -H "X-API-Key: <your-api-key>" \
  "$API_BASE/memories?limit=50&offset=0"

POST

/memories

Queues a new memory write. Requires content and accepts title, tags, and sensitivity.

API key

Create memory

Submit the tenant-scoped write to the queue.

curl -X POST "$API_BASE/memories" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch notes",
    "content": "Copepod is now live.",
    "tags": ["release", "product"],
    "sensitivity": "low"
  }'

GET

/memories/{id}

Returns a single memory by ID. The response includes version, contradiction status, and enrichment fields.

API key

Fetch memory

Get the current memory record by ID.

curl -H "X-API-Key: <your-api-key>" \
  "$API_BASE/memories/<memory-id>"

PUT

/memories/{id}

Queues a full-object update against the current memory version and returns a queued write response.

API key

Update memory

Write updates are queued before consolidation.

curl -X PUT "$API_BASE/memories/<memory-id>" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch notes v2",
    "content": "Copepod is now live with edits.",
    "tags": ["release", "product"]
  }'

DELETE

/memories/{id}

Deletes an accessible memory by ID.

API key

Delete memory

Remove a memory that should no longer exist.

curl -X DELETE "$API_BASE/memories/<memory-id>" \
  -H "X-API-Key: <your-api-key>"

GET

/memories/search

Searches accessible memory. Query parameters include q (required), k, offset, mode (vector-only, hybrid or hybrid+graph), min_quality and an optional agent_id scope filter.

API key

Search memories

Search with the selected retrieval mode and pagination settings.

curl -H "X-API-Key: <your-api-key>" \
  "$API_BASE/memories/search?q=context&k=10&offset=0&mode=hybrid%2Bgraph"

GET

/memories/{id}/versions

Lists all versions for a memory.

API key

List versions

Use this to inspect the write history.

curl -H "X-API-Key: <your-api-key>" \
  "$API_BASE/memories/<memory-id>/versions"

GET

/memories/{id}/versions/{version}

Returns a specific version of a memory.

API key

Get version

Pull a single historical version by number.

curl -H "X-API-Key: <your-api-key>" \
  "$API_BASE/memories/<memory-id>/versions/3"

POST

/memories/{id}/rollback

Rolls a memory back to a previous version using target_version in the body.

API key

Rollback memory

Make an earlier version the current state.

curl -X POST "$API_BASE/memories/<memory-id>/rollback" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "target_version": 3 }'

GET

/usage

Returns usage counters and plan information for the authenticated tenant.

API key

Usage

Read tenant usage for quota and billing flows.

curl -H "X-API-Key: <your-api-key>" \
  "$API_BASE/usage"

Request example

Create a memory

curl and raw HTTP work from any language. The first-party Python SDK is in private beta; see Libraries & SDKs.

curl -X POST "$API_BASE/memories" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch notes",
    "content": "Copepod is now live.",
    "tags": ["release", "product"],
    "sensitivity": "low"
  }'

Base path

/memories

Schemas

Request and response fields

Memory create request

Fields accepted by POST /memories.

Field	Type	Required	Description
title	string	optional	Short display title.
content	string	required	The memory body.
tags	string[]	optional	Searchable labels.
sensitivity	"low" \| "medium" \| "high"	optional	Sensitivity classification.

Memory response

Primary fields returned by the memory API.

Field	Type	Required	Description
memory_id	uuid	required	Stable memory identifier.
status	"active" \| "archived" \| "superseded"	required	Lifecycle state.
version	number	required	Monotonic version number.
contradiction_status	"clear" \| "flagged" \| "resolved"	required	Conflict resolution state.

Search request

Query parameters for GET /memories/search.

Field	Type	Required	Description
q	string	required	Search query text.
k	number	optional	Number of results (default 10).
offset	number	optional	Pagination offset.
mode	"hybrid" \| "hybrid+graph" \| "vector-only"	optional	Retrieval mode. hybrid+graph adds the knowledge graph channel.
min_quality	number	optional	Soft quality threshold from 0 to 1.
agent_id	uuid	optional	Narrows results to one agent's records. It does not establish caller identity.

Search response

Pagination and ranking fields returned by search.

Field	Type	Required	Description
results	MemorySearchResult[]	required	Ranked accessible memories.
total	number	required	Number of matching results in this response scope.
next_cursor	string \| null	optional	Opaque cursor when another page is available.

Response examples

What the API returns

List response

The list endpoint returns a page of results with total and pagination metadata.

{
  "memories": [
    {
      "memory_id": "b0c6d5d9-4b0c-4ebd-bb6c-29cbdb4d7a10",
      "title": "Launch notes",
      "content": "Copepod is now live.",
      "tags": ["release", "product"],
      "sensitivity": "low",
      "status": "active",
      "version": 3,
      "created_at": "2026-04-10T12:00:00Z",
      "updated_at": "2026-04-10T12:05:00Z",
      "contradiction_status": "clear"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Single memory response

The detail endpoint returns the current record with version and conflict state.

{
  "memory_id": "b0c6d5d9-4b0c-4ebd-bb6c-29cbdb4d7a10",
  "tenant_id": "2f2f0ce7-8f35-4d1c-9c1e-1f7f7fd00a48",
  "title": "Launch notes",
  "content": "Copepod is now live.",
  "tags": ["release", "product"],
  "injection_flagged": false,
  "injection_patterns": [],
  "injection_score": 0,
  "created_at": "2026-04-10T12:00:00Z",
  "updated_at": "2026-04-10T12:05:00Z",
  "version": 3,
  "dirty": false,
  "pending_count": 0,
  "contradiction_policy": "NEWER_WINS",
  "contradiction_status": "clear"
}

Search response

Search returns scored results with pagination metadata.

{
  "results": [
    {
      "memory_id": "b0c6d5d9-4b0c-4ebd-bb6c-29cbdb4d7a10",
      "title": "Launch notes",
      "content": "Copepod is now live.",
      "score": 0.982,
      "created_at": "2026-04-10T12:00:00Z",
      "tags": ["release", "product"]
    }
  ],
  "total": 1,
  "offset": 0,
  "k": 10,
  "next_cursor": null
}

Usage response

Usage reports counters and plan information for the tenant.

{
  "memory_count": 12847,
  "storage_used_bytes": 10485760,
  "writes_current_period": 234,
  "reads_current_period": 890,
  "searches_current_period": 441,
  "plan": "free"
}

Notes

Implementation notes

Search requires an authenticated API key and a non-empty q parameter.
Writes are queued first, then consolidated by the worker pipeline.
The response models are derived from the Go structs in cmd/memory-api/main.go and internal/model/memory.go.