Skip to content

Memory API

POST /api/memory

Store a memory.

Same handler as POST /api/context

POST /api/memory and POST /api/context are two routes onto one implementation. Identical body, identical validation, identical response. Pick whichever reads better in your code and stay consistent.

Auth: API key or session.

Body

Field Type Required Default Constraints
project_id string ✅ — Your project key. Created on first write.
agent_id string ✅ — Stored as agent_key.
content string ✅ — 1–8000 characters. The only embedded field.
type string fact One of the six types.
metadata object {} Free-form JSON. Not indexed, not ranked.
confidence float 0.8 0–1. Stored; unused in ranking.
importance float 0.5 0–1. 25 % of the retrieval score.

Types

fact · decision · preference · event · constraint · relationship

Anything else returns 422:

{"detail": "type must be one of fact|decision|preference|event|constraint|relationship"}

Nothing is coerced to a default.

Example

curl -sX POST https://api.venkai.fr/api/memory \
  -H "Authorization: Bearer $VENKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "billing-service",
    "agent_id": "planner",
    "type": "constraint",
    "importance": 0.95,
    "confidence": 1.0,
    "content": "Refunds over 500 EUR require a second approver.",
    "metadata": {"source": "compliance-policy-v3"}
  }'

{
  "id": "ctx_f6f282cb1a2f",
  "org_id": "org_1f200d429c50",
  "project_id": "billing-service",
  "agent_key": "planner",
  "type": "constraint",
  "content": "Refunds over 500 EUR require a second approver.",
  "confidence": 1.0,
  "importance": 0.95,
  "access_count": 0,
  "last_accessed_at": null,
  "created_at": 1787007131.4021,
  "updated_at": 1787007131.4021,
  "metadata": {"source": "compliance-policy-v3"},
  "embedding": ["… raw vector, 128 or 384 floats …"]
}

Behaviour worth knowing

Synchronous embedding. The vector is computed on this request and stored with the row. When you get 200, the memory is immediately retrievable — there is no queue and no eventual consistency.

Projects are created silently. A typo in project_id creates a second, empty project and returns 200. The later read on the correct key then returns nothing, with no error anywhere. Pin the key in a constant.

No deduplication. The same sentence twice is two rows, both retrievable, both consuming retrieval budget.

No delete. Supersede with PATCH /api/context/{id}, or delete the whole organization.

Errors

Status When
401 Missing / invalid / revoked credential
422 Unknown type; content empty or > 8000; importance or confidence outside [0,1]; missing required field
429 Rate limited (production only)

importance, briefly

It is the second-largest term in the ranking formula and the only one that never decays. Spread it across the range or you have surrendered a quarter of the ranking:

Value For
0.9–1.0 Hard constraints, irreversible decisions
0.6–0.8 Decisions with a stated reason
0.4–0.5 Ordinary facts
0.1–0.3 Preferences, ephemera

See Ranking.