API

POST /ingest

Ingest stores one or more memory events and optionally emits companion memories.

Request contract

At minimum, include `entity_id` and `textual_content`. Advanced payloads can include explicit timestamps, memory kind hints, or session metadata.

Use idempotency keys when your producer can retry requests.

Example request

{
  "entity_id": "user-123",
  "memory_id": "user-123::chat-82::42",
  "timestamp": 1763653742000,
  "textual_content": "I moved from NYC to LA last month."
}

Response semantics

`accepted`: memories persisted and indexed
`deduplicated`: memories skipped as duplicates
`invalid`: rejected payload records
`memory_ids`: IDs of accepted primary memories

Example curl

Ingest call

curl -sS http://127.0.0.1:3000/ingest \
  -H "content-type: application/json" \
  -H "x-api-key: XXX1111AAA" \
  -d '{"entity_id":"user-123","memory_id":"mem-001","timestamp":1700000000000,"textual_content":"I moved from NYC to LA."}'