Memories API

Create a memory

POST /v1/memories
Content-Type: application/json

{
  "agentId": "support-agent",
  "subjectId": "customer_acme",
  "pid": "support",
  "tid": "incident-123",
  "content": "Acme prefers Slack escalation for P0 incidents.",
  "metadata": {
    "source": "ticket-123"
  }
}

Required fields are agentId and content. subjectId, pid, tid, metadata, and extractKg are optional. The API generates embeddings and stores them in Vectorize automatically.

The response returns the created memory:

{
  "memory": {
    "id": "7f9d0d2e-6ad1-4a3b-b608-28cbb76b3f87",
    "organization_id": "owner_demo",
    "owner_id": "owner_demo",
    "subject_id": "customer_acme",
    "agent_id": "support-agent",
    "namespace": "support/incident-123",
    "pid": "support",
    "tid": "incident-123",
    "content": "Acme prefers Slack escalation for P0 incidents.",
    "metadata": {
      "source": "ticket-123"
    },
    "vector_id": "mem_7f9d0d2e-6ad1-4a3b-b608-28cbb76b3f87",
    "created_at": "2026-05-18T13:00:00.000Z",
    "updated_at": "2026-05-18T13:00:00.000Z"
  }
}

List memories

GET /v1/memories?agentId=support-agent&pid=support&limit=25

agentId is optional when using an API key. pid, tid, and limit are optional. Limits are capped at 200.

{
  "memories": [
    {
      "id": "7f9d0d2e-6ad1-4a3b-b608-28cbb76b3f87",
      "organization_id": "owner_demo",
      "owner_id": "owner_demo",
      "subject_id": "customer_acme",
      "agent_id": "support-agent",
      "namespace": "support/incident-123",
      "pid": "support",
      "tid": "incident-123",
      "content": "Acme prefers Slack escalation for P0 incidents.",
      "metadata": {},
      "vector_id": null,
      "created_at": "2026-05-18T13:00:00.000Z",
      "updated_at": "2026-05-18T13:00:00.000Z"
    }
  ]
}

Get a memory

GET /v1/memories/:id

Returns { "memory": ... } or a 404 error when the memory does not exist.

Search memories

POST /v1/memories/search
Content-Type: application/json

{
  "agentId": "support-agent",
  "pid": "support",
  "query": "Slack escalation for P0 incidents",
  "limit": 10,
  "includeKg": true
}

The API runs a hybrid retrieval plan: semantic search first, then keyword fallback, with KG fan-out when enabled.

{
  "strategy": "hybrid",
  "mode": "vectorize",
  "memories": [
    {
      "id": "7f9d0d2e-6ad1-4a3b-b608-28cbb76b3f87",
      "agent_id": "support-agent",
      "pid": "support",
      "tid": "incident-123",
      "content": "Acme prefers Slack escalation for P0 incidents.",
      "metadata": "{}",
      "vector_id": "mem:7f9d0d2e-6ad1-4a3b-b608-28cbb76b3f87",
      "created_at": "2026-05-18T13:00:00.000Z",
      "updated_at": "2026-05-18T13:00:00.000Z",
      "score": 0.92,
      "semanticScore": 0.92,
      "keywordScore": 0.5,
      "graphScore": 0.3,
      "recencyScore": 0.96,
      "reasons": ["semantic", "keyword"]
    }
  ],
  "context": {
    "query": "Slack escalation for P0 incidents",
    "items": []
  },
  "triples": []
}

Errors

Validation errors return JSON with an error field:

{
  "error": "organizationId is required"
}