Memory API

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

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

Endpoints

Service surface

GET

/memories

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

Tenant + auth headers

List memories

The list endpoint supports filters and pagination.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/memories?limit=50&offset=0"

POST

/memories

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

Tenant + auth headers

Create memory

Submit the tenant-scoped write to the queue.

curl -X POST "$API_BASE/memories" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  -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.

Tenant + auth headers

Fetch memory

Get the canonical memory record by ID.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/memories/<memory-id>"

PUT

/memories/{id}

Queues an update against the current memory version and returns a queued write response.

Tenant + auth headers

Update memory

Write updates are queued before consolidation.

curl -X PUT "$API_BASE/memories/<memory-id>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch notes v2",
    "content": "Copepod is now live with edits.",
    "tags": ["release", "product"]
  }'

DELETE

/memories/{id}

Deletes the memory and invalidates vector cache entries for the tenant.

Tenant + auth headers

Delete memory

Deletion is immediate and tenant-scoped.

curl -X DELETE "$API_BASE/memories/<memory-id>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>"

GET

/memories/search

Semantic search endpoint. Query params: q (required), k, offset, mode (hybrid|vector|bm25), alpha (0-1 blend weight), explain (returns retrieval scores).

Tenant + auth headers

Search memories

Semantic search uses the embedded query vector and pagination parameters.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/memories/search?q=context&k=10&offset=0&mode=hybrid&alpha=0.7&explain=true"

GET

/memories/{id}/versions

Lists all versions for a memory.

Tenant + auth headers

List versions

Use this to inspect the write history.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/memories/<memory-id>/versions"

GET

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

Returns a specific version of a memory.

Tenant + auth headers

Get version

Pull a single historical version by number.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$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.

Tenant + auth headers

Rollback memory

Repoint the canonical state to a prior version.

curl -X POST "$API_BASE/memories/<memory-id>/rollback" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "target_version": 3 }'

POST

/memories/{id}/enrich

Triggers progressive enrichment for a memory via the worker pipeline.

Tenant + auth headers

Trigger enrichment

Kick off enrichment for the memory.

curl -X POST "$API_BASE/memories/<memory-id>/enrich" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>"

GET

/memories/{id}/status

Returns dirty state, pending write count, and contradiction policy for a memory.

Tenant + auth headers

Check status

Inspect queue state before or after consolidation.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/memories/<memory-id>/status"

GET

/usage

Returns usage counters and plan information for the authenticated tenant.

Tenant + auth headers

Usage

Read tenant usage for quota and billing flows.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  "$API_BASE/usage"

Request example

Create a memory

The create endpoint queues a write and accepts a minimal payload.

curl -X POST "$API_BASE/memories" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch notes",
    "content": "Copepod is now live.",
    "tags": ["release", "product"],
    "sensitivity": "low"
  }'

Base path

/memories

Schemas

OpenAPI-style field tables

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" \| "vector" \| "bm25"	optional	Search mode: hybrid combines vector + BM25 (default), vector uses only embedding similarity, bm25 uses only keyword search.
alpha	number	optional	Blend weight for hybrid mode (0.0-1.0, default 0.5). Higher values favor vector search.
explain	boolean	optional	When true, include retrieval explainability data in response (vector_score, bm25_score, combined_score).

Search response (with explain)

Fields returned when explain=true.

Field	Type	Required	Description
mode	string	required	Search mode used.
alpha	number	required	Blend weight applied.
vector_score	number	required	Embedding similarity score (0-1).
bm25_score	number	required	BM25 keyword score.
combined_score	number	required	Final combined relevance score.

Response examples

What the API returns

List response

The list endpoint wraps the page of results with total and cursor 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 tenant record with queue and contradiction 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,
  "explanation": {
    "mode": "hybrid",
    "alpha": 0.7,
    "vector_score": 0.964,
    "bm25_score": 0.85,
    "combined_score": 0.982
  }
}

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 tenant context 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.