Documentation

Memory

Memory is 100% local: BGE-M3 embeddings run in a dedicated container; text is stored in pgvector inside our PostgreSQL. Nothing is sent to a third-party model. Measured: hit@1 = 19/25 overall, 8/10 on Egyptian-dialect queries (P2.5 eval).

POST /v1/memory/write api-key · memory:write #

Store text in your private memory. Items are deduplicated by normalized text hash — re-writing the same text updates it.

Request

FieldTypeDescription
itemsarrayrequiredArray of items to store (max 64 per call).
items[].textstringrequiredThe text to remember.
items[].sourceUrlstringoptionalOptional source URL for provenance.
items[].tagsstring[]optionalOptional tags for filtered retrieval.

Example

curl -X POST https://agw.orcanox.xyz/v1/memory/write \
  -H "Authorization: Bearer agw_…" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"text":"The renewal price is $90/year","sourceUrl":"https://example.com/pricing","tags":["pricing"]}]}'

Response

json
{
  "written": 2,
  "updated": 0,
  "ids": [
    "<id-1>",
    "<id-2>"
  ]
}

Errors

StatuscodeExample
400bad_request{"code":"bad_request","message":"text normalizes to empty — nothing to store"}
DELETE /v1/memory/:id api-key · memory:write #

Delete one memory item by id. Tenant-scoped: a foreign id is indistinguishable from a missing one.

Request

FieldTypeDescription
id (path)stringrequiredThe memory item id.

Example

curl -X DELETE https://agw.orcanox.xyz/v1/memory/<id> \
  -H "Authorization: Bearer agw_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

json
{
  "deleted": true,
  "id": "<id>"
}

Errors

StatuscodeExample
404not_found{"code":"not_found","message":"memory item not found"}