Memories

Store a memory

POST /v1/record
Authorization: Bearer anona_live_YOUR_KEY
Content-Type: application/json

{
  "space_id": "customer-support-bot",
  "content": "Alice works at Google and specializes in distributed systems",
  "context": "onboarding call",
  "user_id": "alice_123",
  "tags": ["work", "expertise"],
  "metadata": { "source": "crm" }
}

Parameter	Type	Required	Description
`space_id`	string	Yes	Which space to store in.
`content`	string	Yes	The memory text.
`context`	string	No	Freeform context for the memory.
`timestamp`	string	No	ISO 8601 event time: when the thing happened, not when you are recording it. Set it when importing history. Returned as `timestamp` on retrieve, used in recency ranking, and what `occurred_after` / `occurred_before` match against. It is not copied into `occurred_start`, which is read from the memory’s own text. Defaults to now. See Searching over time.
`user_id`	string	No	End user this memory belongs to. Only a search carrying the same `user_id` returns it. See Scoping.
`agent_id`	string	No	Agent that produced or owns this memory.
`session_id`	string	No	Conversation or run this memory came from.
`tags`	string[]	No	Visibility-scope tags; `retrieve` can filter on them. Tags starting with `anona:` are reserved.
`metadata`	object	No	Custom key-value data, returned on retrieval.
`async`	boolean	No	When `true`, queues the write and returns a `job_id` instead of waiting. Defaults to `false`.

user_id is a real field, not metadata. Putting a user id in metadata stores it but does not isolate anything: metadata is returned with results, never filtered on.

Response 201 Created

{
  "memory_id": "mem_abc123def456",
  "status": "stored",
  "usage": {
    "input_tokens": 42,
    "output_tokens": 12
  }
}

A synchronous write is slow, and async is roughly ten times faster. A memory is analyzed by a language model and its facts extracted before the call returns, so record waits for that work. Measured against production with a one-sentence memory:

Call	Time
`record`	12-17 seconds
`record` with `"async": true`	1-3 seconds

Anything a person is waiting on (a chat turn, a form submit, a page transition) should use async mode below. Reach for a synchronous write only when the very next thing you do is search for what you just stored.

Store a memory asynchronously

Set "async": true and the call returns in about a second with a job_id and status: "processing" in place of the stored memory_id. The memory is extracted and indexed in the background; poll the job to learn when it is searchable. This is the recommended way to write. The extraction work is identical and costs the same; you simply stop waiting for it. The one thing that changes is timing: the memory is not searchable the instant the call returns, so a flow that writes and then immediately retrieves needs to wait for the job (or use a synchronous write).

{
  "space_id": "customer-support-bot",
  "content": "Alice works at Google and specializes in distributed systems",
  "async": true
}

{
  "memory_id": null,
  "job_id": "job_9f2a1c",
  "status": "processing"
}

job = client.record(
    space_id="customer-support-bot",
    content="Alice works at Google and specializes in distributed systems",
    background=True,
)
print(job["job_id"])  # poll this

Pair async writes with webhooks and you can drop polling entirely: Anona posts to your endpoint when the memory is stored.

Bulk ingest

Queue many memories in a single call, which is the efficient way to backfill history. Bulk ingest is always asynchronous: the batch is accepted and a job_id returned immediately.

POST /v1/record/batch
Authorization: Bearer anona_live_YOUR_KEY
Content-Type: application/json

{
  "space_id": "customer-support-bot",
  "items": [
    { "content": "Alice works at Google." },
    { "content": "Bob prefers async standups.", "context": "team sync" },
    { "content": "The Q3 launch slipped to October.", "timestamp": "2026-06-01T00:00:00Z" }
  ]
}

Parameter	Type	Required	Description
`space_id`	string	Yes	Which space to store in.
`items`	array	Yes	1 to 100 memory objects. Each takes the same fields as `record`: `content` is required; `context`, `timestamp`, `metadata`, `tags`, and the scope keys `user_id` / `agent_id` / `session_id` are optional.
`user_id` / `agent_id` / `session_id`	string	No	Scope applied to every item — a batch is usually one user’s history. An item’s own scope keys override these.

Response 202 Accepted

{
  "job_id": "job_batch_71b3",
  "job_ids": ["job_batch_71b3"],
  "status": "processing",
  "accepted": 3
}

accepted is the number of items queued. Poll job_id for progress. A large batch may be split into several operations, all listed under job_ids.

To send more than 100 items, chunk them into multiple calls. Each item is charged a base cost when queued and reconciled to its real cost once processing finishes, exactly as a synchronous write is, so queuing does not make ingestion cheaper.

Job status

Checks a job returned by an async record or by record/batch. This read is free and consumes no credits.

GET /v1/spaces/{space_id}/jobs/{job_id}
Authorization: Bearer anona_live_YOUR_KEY

{
  "job_id": "job_9f2a1c",
  "status": "completed",
  "created_at": "2026-07-20T10:00:00Z",
  "completed_at": "2026-07-20T10:00:03Z",
  "error": null,
  "memory_count": 2,
  "memory_ids": ["mem_...", "mem_..."],
  "progress": null
}

memory_count and memory_ids are set once the job completes — they are how you address the memories an async write produced. While a batch is running, progress carries {stage, processed, total, parts_done, parts_total, memories_stored, updated_at}; processed/total count chunks in the parts that have started, so parts_done / parts_total and status are the completion signals, not processed == total.

`status`	Meaning	Terminal
`pending`	Queued, not started yet.	No
`processing`	Being extracted and stored.	No
`completed`	Stored and searchable.	Yes
`failed`	Processing failed. See `error`.	Yes
`cancelled`	The job was cancelled.	Yes
`not_found`	No such job in this space.	Yes

A 404 is returned when the job_id does not belong to the space.

Poll until complete

KEY="anona_live_YOUR_KEY"
SPACE="customer-support-bot"

# 1. Queue the write, capture the job_id
JOB=$(curl -s https://api.anonalabs.com/v1/record \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"space_id":"'"$SPACE"'","content":"Alice works at Google.","async":true}' \
  | jq -r .job_id)

# 2. Poll every 2s until it stops processing
while true; do
  STATUS=$(curl -s "https://api.anonalabs.com/v1/spaces/$SPACE/jobs/$JOB" \
    -H "Authorization: Bearer $KEY" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    completed|failed|cancelled|not_found) break ;;
  esac
  sleep 2
done

import time

# 1. Queue the write (background mode returns a job, not a stored memory)
job = client.record(
    space_id="customer-support-bot",
    content="Alice works at Google.",
    background=True,
)
job_id = job["job_id"]

# 2. Poll until the job reaches a terminal state
while True:
    status = client.get_job(space_id="customer-support-bot", job_id=job_id)
    print("status:", status["status"])
    if status["status"] in ("completed", "failed", "cancelled", "not_found"):
        break
    time.sleep(2)

if status["status"] == "failed":
    raise RuntimeError(status["error"])

A record/batch job is polled exactly the same way. completed means every item in the batch has been stored and is searchable.

Cancel a job

Stops an ingestion job that has not finished. Cancelling is free, consumes no credits, and is never refused for an empty balance: a runaway import must always be stoppable.

DELETE /v1/spaces/{space_id}/jobs/{job_id}
Authorization: Bearer anona_live_YOUR_KEY

Response 200 OK

{
  "job_id": "job_batch_71b3",
  "status": "cancelled",
  "cancelled_parts": 4,
  "running_parts": 1
}

A job is split into parts that run independently, and only a part still queued can be stopped. A part already being processed runs to completion. cancelled_parts is what this call stopped; running_parts is what it could not, so poll the job afterwards to see those finish.

Response	When
`200`	At least one queued part was stopped, or the job was already cancelled.
`403 space_read_only`	The caller has read-only access to the space.
`404`	No job with that id in this space.
`409 job_not_cancellable`	Every part had already started or finished. Nothing was stopped.

Cancelling does not undo work already done. Memories written by parts that ran stay stored and searchable, and the base cost charged when the job was queued is not refunded — but the parts that never run are never charged for the extraction they would have done.

cURL

curl -X DELETE "https://api.anonalabs.com/v1/spaces/$SPACE/jobs/$JOB" \
  -H "Authorization: Bearer $KEY"

List memories in a space

GET /v1/spaces/{space_id}/memories?limit=10&offset=0&q=Alice&type=fact
Authorization: Bearer anona_live_YOUR_KEY

Query parameter	Type	Description
`limit`	integer	Maximum results to return. Default 50, maximum 200.
`offset`	integer	Pagination offset.
`q`	string	Optional text filter.
`type`	string	Optional memory type filter: `fact`, `note`, `experience`, or `summary`, the same labels the response returns.
`state`	string	`active` (default) lists live memories; `invalidated` lists retired ones kept for audit.
`prefer_observations`	boolean	Defaults to `true`: list one row per piece of knowledge. Set `false` to also list the raw facts a `note` was synthesized from.
`user_id` / `agent_id` / `session_id`	string	List only memories in that scope. Strict: untagged memories never match a scoped listing.
`member_id`	string	Only memories written by this member; pass `me` for your own. Attribution exists only in spaces shared across organizations.

Response 200 OK

{
  "items": [
    {
      "id": "mem_abc123def456",
      "text": "Alice works at Google and specializes in distributed systems",
      "context": "onboarding call",
      "date": "2026-07-14T12:34:56Z",
      "type": "fact",
      "entities": "Alice, Google",
      "state": "active",
      "metadata": {"user_id": "alice_123"},
      "source_ids": []
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Anona stores knowledge in two layers: the raw facts you record, and the note it synthesizes from them once they settle. Both describe the same thing, so listing them side by side reads as duplicates, so by default this endpoint returns the note and hides the facts folded into it. source_ids names those facts, and prefer_observations=false lists them as rows of their own. total follows the same rule, so paging stays consistent either way.

List results use different field names from the rest of the API. Map them before reusing the objects elsewhere.

List field	Equivalent when writing or retrieving
`id`	`memory_id`
`text`	`content`
`date`	`created_at`

entities also differs in shape: the list returns a single comma-separated string, while retrieve returns an array of strings.

Edit or retire a memory

Correct what was stored, or reversibly retire it. Every field is optional; only what you send changes.

PATCH /v1/spaces/{space_id}/memories/{memory_id}
Authorization: Bearer anona_live_YOUR_KEY
Content-Type: application/json

{
  "text": "Alice works at Google as a staff engineer.",
  "reason": "Title corrected after the onboarding call."
}

Field	Type	Description
`text`	string	Replacement memory text. The memory is re-embedded and re-consolidated.
`context`	string	Replacement context.
`occurred_start` / `occurred_end`	string	Corrected event time (ISO 8601).
`memory_type`	string	Typically `fact` or `experience`. Validated by the engine, not at the gateway.
`entities`	string[]	Replaces the memory’s entity set; `[]` detaches all.
`state`	string	`invalidated` drops the memory out of retrieve, consolidation and reasoning while keeping it for audit; `active` restores it.
`reason`	string	Free-text audit note, kept on the memory’s history.

The response is the updated memory in the same shape the list returns, including its state, so an invalidate or restore can be confirmed from the reply. Notes (type: "note") cannot be edited — they are synthesized, and the engine rejects the attempt rather than letting a synthesis drift from its evidence.

Memory history

Memories are living records. As new information arrives, Anona updates what it knows and keeps the previous version. Fetch a memory’s history to see what it said before and when it changed.

GET /v1/spaces/{space_id}/memories/{memory_id}/history
Authorization: Bearer anona_live_YOUR_KEY

{
  "memory_id": "mem_abc123def456",
  "history": [
    {
      "previous_content": "Works at Google.",
      "changed_at": "2026-07-18T14:07:31Z",
      "previous_occurred_start": null,
      "previous_occurred_end": null
    }
  ]
}

Field	Description
`previous_content`	What the memory said before the change.
`changed_at`	When that version was superseded.
`previous_occurred_start` / `previous_occurred_end`	The event time that version referred to.
`reason`	The audit note a PATCH supplied for the change. Null on versions rewritten by Anona’s own consolidation.

Entries are written both by Anona’s own consolidation and by your edits. An empty history array means the memory has never changed.

Delete a memory

DELETE /v1/spaces/{space_id}/memories/{memory_id}
Authorization: Bearer anona_live_YOUR_KEY

client.delete_memory(space_id="customer-support-bot", memory_id="mem_abc123def456")

Response 204 No Content. The deletion is permanent and the body is empty. There is no endpoint for fetching a single memory by id — read one through listing or retrieve. Updating one is PATCH, above.

Error responses

Status	Code	Cause
401	`missing_auth` / `invalid_api_key`	Missing or invalid API key.
403	`space_access_denied`	You are not a member of this space.
404	`space_not_found`	The space does not exist. A missing memory id is a 404 with a descriptive message.
422	`validation_error`	The body fails schema validation.
429	`rate_limited`	Credit quota or rate limit exceeded.

See the full error reference.

Next steps

Retrieve API

Query memories semantically.

Reason API

Synthesize an answer across memories.

Documents

Ingest files into the same space.

Webhooks

Get told when ingestion finishes.

Getting Started

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

SDKs & MCP

Integrations

Guides

Changelog

Store a memory

Store a memory asynchronously

Bulk ingest

Job status

Poll until complete

Cancel a job

List memories in a space

Edit or retire a memory

Memory history

Delete a memory

Error responses

Next steps

Retrieve API

Reason API

Documents

Webhooks

​Store a memory

​Store a memory asynchronously

​Bulk ingest

​Job status

​Poll until complete

​Cancel a job

​List memories in a space

​Edit or retire a memory

​Memory history

​Delete a memory

​Error responses

​Next steps

Retrieve API

Reason API

Documents

Webhooks

Store a memory

Store a memory asynchronously

Bulk ingest

Job status

Poll until complete

Cancel a job

List memories in a space

Edit or retire a memory

Memory history

Delete a memory

Error responses

Next steps