Docs

Ebb Memory Engine API

Production cognitive memory engine and multi-transport gateway for autonomous AI agents. Features continuous mass-dilated logarithmic decay, Hebbian co-activation networks, off-heap mmap storage, and unified enterprise security. Canonical public HTTP contract for Ebb client SDKs. Generated from the hosted FastAPI application. Excludes internal and admin routes. Protected operations require `Authorization: Bearer <token>` (security scheme `HTTPBearer`). The same routes accept an optional `X-API-Key` header and `X-Ebb-Namespace` to select a namespace. Error responses use the `ErrorResponse` envelope (`code`, `message`, `details`) plus FastAPI's `HTTPValidationError` for 422. SDK subset of the Ebb HTTP contract. Includes Memory, Tasks, Events, and Health. Omits admin, runtime config, provider probes, registration, password reset, and SSO.

Version 0.2.0. Same document as Redoc and Swagger UI.

QuickstartRedocSwagger UI

Health

Liveness at GET /healthz and readiness at GET /readyz.

GET/healthz

Healthz

health

Liveness probe endpoint.

Responses: 200 Successful Response · 400

GET/readyz

Readyz

ready

Readiness probe endpoint.

Responses: 200 Successful Response · 400

Memory

Cognitive memory storage, fused 6-phase scoring retrieval, and synaptic reinforcement.

POST/api/v1/memory/remember

Remember

remember

Ingest observation into cognitive memory tier.

Parameters

  • X-Ebb-Namespace header

Body RememberRequestModel, required. Required fields: content.

Responses: 201 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/remember/batch

Remember Batch

rememberBatch

Batch ingest memories.

Parameters

  • X-Ebb-Namespace header

Body BatchRememberRequestModel, required. Required fields: items.

Responses: 201 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/recall

Recall Get

recallQuery

Retrieve memories using cognitive scoring scan (GET).

Parameters

  • query query required
  • limit query
  • profile query
  • min_score query
  • domain query
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/recall

Recall Post

recall

Retrieve memories using cognitive scoring scan (POST).

Parameters

  • X-Ebb-Namespace header

Body RecallRequestModel, required. Required fields: query.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/recall/federated

Recall Federated Get

recallFederatedQuery

Retrieve memories across multiple namespaces using federated rank fusion (GET).

Parameters

  • query query required
  • namespaces query
  • limit query
  • profile query
  • min_score query
  • domain query
  • salience_weights query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/recall/federated

Recall Federated Post

recallFederated

Retrieve memories across multiple namespaces using federated rank fusion (POST).

Parameters

  • X-Ebb-Namespace header

Body FederatedRecallRequest, required. Required fields: query.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/reinforce

Reinforce

reinforce

Reinforce Hebbian associations or memory trace.

Parameters

  • X-Ebb-Namespace header

Body ReinforceRequestModel, required. Required fields: memory_id.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/dream

Dream

dream

Trigger sleep consolidation generative replay rest cycle.

Parameters

  • X-Ebb-Namespace header

Body DreamRequestModel, required.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/reflect

Reflect

reflect

Trigger self-model reflection and crystallization.

Parameters

  • X-Ebb-Namespace header

Body ReflectRequestModel, required.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/wander

Wander

wander

Trigger Default Mode Network stochastic associative walk.

Parameters

  • X-Ebb-Namespace header

Body WanderRequestModel, required.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/introspect

Introspect

introspect

Retrieve cognitive state and topological graph summary.

Parameters

  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/status

Status Endpoint

status

Retrieve health check and storage slab capacity stats.

Parameters

  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/why-not

Why Not

whyNot

Explain why candidate engram was dropped during retrieval.

Parameters

  • X-Ebb-Namespace header

Body WhyNotRequestModel, required. Required fields: memory_id, query.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/table

List Memories

listMemoriesTable

Retrieve paginated and filtered table rows of memory traces via cursor or page seeking.

Parameters

  • cursor query
  • limit query
  • tier query
  • tags query
  • tombstoned query
  • search query
  • namespace query
  • page query
  • page_size query
  • min_importance query
  • min_valence query
  • max_valence query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory

List Memories

listMemories

Retrieve paginated and filtered table rows of memory traces via cursor or page seeking.

Parameters

  • cursor query
  • limit query
  • tier query
  • tags query
  • tombstoned query
  • search query
  • namespace query
  • page query
  • page_size query
  • min_importance query
  • min_valence query
  • max_valence query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/vacuum

Vacuum Endpoint

vacuum

Reclaim slab space from tombstones and trigger deep consolidation.

Parameters

  • X-Ebb-Namespace header

Body VacuumRequest, required.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/{memory_id}

Get Memory Detail Endpoint

getMemory

Retrieve full details of a specific memory engram.

Parameters

  • memory_id path required
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

PATCH/api/v1/memory/{memory_id}

Update Memory Endpoint

updateMemory

Update cognitive attributes on an existing memory engram.

Parameters

  • memory_id path required
  • namespace query
  • X-Ebb-Namespace header

Body UpdateMemoryRequest, required.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

DELETE/api/v1/memory/{memory_id}

Delete Memory Endpoint

forgetMemory

Tombstone (soft-delete) or physically purge a memory trace.

Parameters

  • memory_id path required
  • purge query
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

DELETE/api/v1/memory/{memory_id}/purge

Purge Memory Endpoint

purgeMemory

Irreversibly physically destroy an engram across slabs, bundles, and graphs.

Parameters

  • memory_id path required
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/graph/overview

Graph Overview Endpoint

graphOverview

Sample topological nodes and Hebbian co-activation edges for 3D visualizers.

Parameters

  • max_nodes query
  • offset query
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/{memory_id}/graph

Get Memory Neighborhood Endpoint

getMemoryGraph

Retrieve synaptic neighborhood graph centered on a target memory trace.

Parameters

  • memory_id path required
  • depth query
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/{memory_id}/vector

Get Memory Vector Endpoint

getMemoryVector

Retrieve 16-lane SIMD vector embedding for target memory trace.

Parameters

  • memory_id path required
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/mel

Execute Mel Endpoint

executeMel

Execute one or more MEL-001 (Memory Engine Language) statements.

Parameters

  • X-Ebb-Namespace header

Body MelExecuteRequest, required. Required fields: script.

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/memory/remember/upload

Remember Upload Endpoint

rememberUpload

Sensory file/folder upload adapter returning 202 Accepted with background task descriptor .

Parameters

  • wait query
  • Idempotency-Key header
  • X-Ebb-Namespace header

Responses: 202 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/memory/{memory_id}/document

Get Memory Document Endpoint

getMemoryDocument

Reconstruct the full de-overlapped document from any constituent chunk memory ID.

Parameters

  • memory_id path required
  • namespace query
  • X-Ebb-Namespace header

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

Tasks

Background document and folder ingestion task lifecycle, progress inspection, and cancellation .

GET/api/v1/tasks

List Ingestion Tasks

listTasks

List background ingestion tasks visible to the authenticated caller.

Parameters

  • status query
  • namespace query
  • limit query

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

GET/api/v1/tasks/{task_id}

Get Ingestion Task

getTask

Retrieve status, counters, timestamps, and error summary for a specific ingestion task.

Parameters

  • task_id path required

Responses: 200 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

DELETE/api/v1/tasks/{task_id}

Cancel Ingestion Task

cancelTask

Request cooperative cancellation of a queued or running ingestion task (idempotent).

Parameters

  • task_id path required

Responses: 202 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

POST/api/v1/tasks/{task_id}/cancel

Cancel Ingestion Task

cancelTaskByPost

Request cooperative cancellation of a queued or running ingestion task (idempotent).

Parameters

  • task_id path required

Responses: 202 Successful Response · 400 Bad Request — constraint violation or malformed input · 401 Unauthorized — missing or invalid Bearer JWT / X-API-Key · 403 Forbidden — insufficient role permissions or policy violation · 404 Not Found — target memory trace, thread, or tenant not found · 422 Validation Error · 429 Too Many Requests — token bucket rate limit budget exceeded

Events

Server-Sent Events (SSE) memory lifecycle streaming with Last-Event-ID cursor replay.

GET/api/v1/events/stream

Event Stream

streamEvents

Stream live memory and ingestion lifecycle events over SSE with Last-Event-ID replay.

Parameters

  • last_event_id query
  • event_types query
  • namespace query
  • namespaces query
  • Last-Event-ID header
  • token query

Responses: 200 Successful Response · 422 Validation Error