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).
Store text in your private memory. Items are deduplicated by normalized text hash — re-writing the same text updates it.
Request
| Field | Type | Description | |
|---|---|---|---|
items | array | required | Array of items to store (max 64 per call). |
items[].text | string | required | The text to remember. |
items[].sourceUrl | string | optional | Optional source URL for provenance. |
items[].tags | string[] | optional | Optional 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"]}]}'
import requests r = requests.post("https://agw.orcanox.xyz/v1/memory/write", headers={"Authorization": "Bearer agw_…"}, json={"items":[{"text":"The renewal price is $90/year","sourceUrl":"https://example.com/pricing","tags":["pricing"]}]}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/v1/memory/write", { method: "POST", headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" }, body: JSON.stringify({"items":[{"text":"The renewal price is $90/year","sourceUrl":"https://example.com/pricing","tags":["pricing"]}]}) }); console.log(r.status, await r.json());
Response
json
{
"written": 2,
"updated": 0,
"ids": [
"<id-1>",
"<id-2>"
]
}Errors
| Status | code | Example |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"text normalizes to empty — nothing to store"} |
Semantic search over your memory — hybrid score: 0.7·embedding cosine + 0.3·text similarity. Egyptian-dialect queries are mapped to MSA automatically.
Request
| Field | Type | Description | |
|---|---|---|---|
query | string | required | What to look for. |
k | integer | optional | Max results (default 10). |
minScore | number | optional | Minimum hybrid score (default 0.35). |
tags | string[] | optional | Only items carrying any of these tags. |
Example
curl -X POST https://agw.orcanox.xyz/v1/memory/search \ -H "Authorization: Bearer agw_…" \ -H "Content-Type: application/json" \ -d '{"query":"renewal price","k": 5}'
import requests r = requests.post("https://agw.orcanox.xyz/v1/memory/search", headers={"Authorization": "Bearer agw_…"}, json={"query":"renewal price","k": 5}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/v1/memory/search", { method: "POST", headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" }, body: JSON.stringify({"query":"renewal price","k": 5}) }); console.log(r.status, await r.json());
Response
json
{
"items": [
{
"id": "<id>",
"text": "…",
"sourceUrl": "https://…",
"tags": [
"docs"
],
"createdAt": "2026-10-01T12: 00: 00.000Z",
"score": 0.78
}
],
"tookMs": 95
}Errors
| Status | code | Example |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"query normalizes to empty — nothing to match"} |
Delete one memory item by id. Tenant-scoped: a foreign id is indistinguishable from a missing one.
Request
| Field | Type | Description | |
|---|---|---|---|
id (path) | string | required | The memory item id. |
Example
curl -X DELETE https://agw.orcanox.xyz/v1/memory/<id> \ -H "Authorization: Bearer agw_…" \ -H "Content-Type: application/json" \ -d '{}'
import requests
r = requests.delete("https://agw.orcanox.xyz/v1/memory/<id>", headers={"Authorization": "Bearer agw_…"}, json={})
print(r.status_code, r.json())const r = await fetch("https://agw.orcanox.xyz/v1/memory/<id>", {
method: "DELETE",
headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" },
body: JSON.stringify({})
});
console.log(r.status, await r.json());
Response
json
{
"deleted": true,
"id": "<id>"
}Errors
| Status | code | Example |
|---|---|---|
| 404 | not_found | {"code":"not_found","message":"memory item not found"} |