Memories API

Base URL: http://localhost:4545/api/v1

Protected endpoints require Authorization: Bearer $REMEM_SERVER_API_KEY.

Create a memory

POST /memories

{
  "content": "User prefers concise answers.",
  "policy": "long_term",
  "ttl_seconds": 0,
  "tags": ["preference", "communication"],
  "importance": 0.8
}

policy selects the lifecycle policy. ttl_seconds is required by the create contract and is normally 0 for policies without a time limit. Tags are capped at 50 per memory. Relationship discovery is queued durably after the write.

Search

POST /memories/search

{
  "query": "How should this user receive information?",
  "search_type": "hybrid",
  "limit": 10,
  "tags": ["preference"]
}

search_type is explicit on every search: semantic uses vector similarity, keyword uses the text index, and hybrid combines both by rank. Filters narrow the candidates; they do not add a separate path to the result set.

Get, update, and delete

GET /memories/{id}
PATCH /memories/{id}
DELETE /memories/{id}?hard=false

Use PATCH for partial updates. A normal delete archives the memory and removes it from active search; hard=true removes it permanently. Fetching a memory can record a durable recall event, which lifecycle maintenance uses to keep useful context alive.

List memories

GET /memories?limit=20&order_by=created_at&order=desc

Listing supports indexed filters, five orderings, opaque continuation cursors, and an explicit truncated/has_more response contract. Archived memories are excluded unless the request opts in.

Related memories

GET /memories/{id}/related?depth=2&limit=20

This traverses the durable relationship graph. Connections can be discovered automatically or created explicitly through the connections API.

Response and errors

Successful writes return the memory and its durable id. Errors use a consistent problem response with a request id, making client failures and server logs easier to correlate. Tenant boundaries are enforced on every memory operation.