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",
  "session_id": "chat-82",
  "textual_content": "I moved from NYC to LA last month.",
  "created_at_ms": 1763653742000
}

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","textual_content":"I moved from NYC to LA."}'