Long-term memory
Sellable product
This capability is granted by an API key scoped to the `` product (product face). See the product reference below.
Per-(organization, user) cross-session agent memory as a shared capability. Consumers: voice + aakhara (agent products that need the user remembered across calls/sessions) = >=2. INTERNAL (no product-face). Fail-closed: /v1/memories returns 503 when the LLM extraction edge (provider-gateway) is unconfigured.
- Group: Voice & AI
- Contract:
contracts/long-term-memory/v1/openapi.yaml - Public base:
https://api.vagarylabs.com(the consolidated API gateway — one host, per-brand siblingapi.<zone>) - Auth: a product API key (
vgk_…) issued from the console —Authorization: Bearer vgk_… - Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/memory/store
Endpoints
| Method | Path | Summary |
|---|---|---|
POST | /v1/memories | Add memories from raw turns/text (extract → consolidate/dedup → store) |
GET | /v1/memories | List a user's memories (most-recently-updated first) |
DELETE | /v1/memories | GDPR (Art.17) erasure — forget EVERY memory for a user within the tenant |
GET | /v1/memories/search | Semantic recall of a user's memories relevant to a query (ranked) |
DELETE | /v1/memories/{memory_id} | Forget one memory (IDOR-safe — scoped by org+user+id) |
GET | /health | liveness (db + embedder + llm-configured) |
GET | /metrics | Prometheus exposition |
Schemas
Error
| Field | Type | Description |
|---|---|---|
error | string | stable machine code (slug), e.g. validation_error, unauthorized, upstream_failed, internal |
reason | string | human-readable one-line explanation (no secrets/PII) |
detail | object | |
request_id | string |
AddMemoryRequest
| Field | Type | Description |
|---|---|---|
organization_id | string | product-tier tenant (I6); resolved anti-spoof when identity is wired |
user_id | string | end-user within the tenant (sub-tenant scope) |
messages | array | chat turns to extract memories FROM (alt to text) |
text | string | raw text to extract memories FROM (alt to messages) |
metadata | object | stored on new memories |
AddMemoryResponse
| Field | Type | Description |
|---|---|---|
memory_ids | array | ids added or updated this call |
added | integer | |
updated | integer | |
deleted | integer |
Memory
| Field | Type | Description |
|---|---|---|
id | string | |
content | string | |
metadata | object | |
score | number | search only — 1 - cosine distance (higher = more relevant) |
created_at | string | |
updated_at | string |
MemoryList
| Field | Type | Description |
|---|---|---|
organization_id | string | |
user_id | string | |
count | integer | |
memories | array |
SearchResponse
| Field | Type | Description |
|---|---|---|
organization_id | string | |
user_id | string | |
count | integer | |
memories | array |
Generated by scripts/gen-capability-docs.py from contracts/long-term-memory/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.