- Sells as: the
memory product (a product-scoped API key). This capability has no separate product-face contract — its public product route reuses the capability contract below; see the Edge route table's Product face row.
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
- Console: Manage the
memory product in the console →
- Runbook: operational checklist for
long-term-memory — internal (Vagary Labs ops; not part of this public site): docs/runbooks/capability-operations.md#long-term-memory
- Public base:
https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<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
Edge route table
The routes this capability actually serves on the public edge — live-synced from GET https://api.vagarylabs.com/product/v1/_meta/catalog (snapshot v1). The metric is the request-granularity billing counter; the scope is the key permission required.
Product face (customer-keyed)
| Method | Path | Metric | Scope |
|---|
POST | /product/v1/memory/store | memory_operations | write |
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. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.