API reference

REST API

Every endpoint of the cloud API and the self hosted server.

llms.txt

Two REST surfaces expose process_turn: the cloud endpoint and the self-hosted server, both with Bearer auth. The self-hosted server also exposes the rest of the engine: memory updates and supersession, paged lists, hybrid search (also across databases in one call), heads up context, history, the graph, pins, documents, maintenance and backups. Any language that can send JSON works.

Cloud endpoint

POST https://api.mentedb.com/v1/process_turn with an Authorization: Bearer $MENTEDB_API_KEY header. The body carries the turn fields directly.

Terminal
curl -X POST https://api.mentedb.com/v1/process_turn \
  -H "Authorization: Bearer $MENTEDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_message":"I switched from Postgres to SQLite",
        "assistant_response":"Noted.",
        "turn_id":0}'

The response is the turn data directly as JSON (a context array and a contradictions count), so clients call resp.json() with no unwrapping.

JSON
{ "context": [...], "contradictions": 0 }

The MCP tool endpoint under https://api.mentedb.com/mcp also exists for no-code connectors, but new integrations should use the clean endpoint above. Full runnable Python and Node clients are in Cloud (REST).

Cloud memory endpoints

The cloud also serves the memory store under https://api.mentedb.com/api/memories, with the same mdb_ key.

EndpointWhat it does
GET /api/memoriesList memories with filters, sort and a cursor. ?session_id= and ?source= filter by provenance.
POST /api/memoriesStore a note: content, and optionally memory_type, scope, tags, session_id and source_ref. Recorded with source api.
GET /api/memories/{id}One memory with its provenance.
DELETE /api/memories/{id}Forget one memory. Its bytes stay until the space is reused.
GET /api/memories/sessionsThe sessions the account's memories were written in, each with its memory count: {"sessions": [{"session_id", "memories"}]}.
POST /api/memories/{id}/eraseVerified erase of one memory and everything derived from it. Answers 200 with the receipt, or 202 with a status_url.
POST /api/memories/sessions/{session_id}/eraseVerified erase of everything a session wrote, with one receipt. 200 or 202 with a status_url. See Erase and forgetting.
GET /api/memories/jobs/{job_id}Read an erase job until status is no longer running. Kept for an hour after it finishes.
POST /v1/memory_toolThe memory tool backend, same contract as the server. See Claude memory tool.

Self-hosted server

The server listens on 6677 (REST) and 6678 (gRPC). Every database route below exists twice: under /v1 for the default database and under /v1/db/{db} for a named one (see Databases & tokens). With auth on, send Authorization: Bearer $TOKEN. Times are Unix microseconds. Lists take ?limit= (default 50, max 1000).

Terminal
# Store a memory
curl -X POST http://localhost:6677/v1/memories \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"agent_id": "00000000-0000-0000-0000-000000000001",
       "content": "User prefers dark mode", "memory_type": "semantic",
       "tags": ["preferences"]}'

# Recall via MQL
curl -X POST http://localhost:6677/v1/recall \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query": "RECALL memories WHERE tag CONTAINS \"preferences\" LIMIT 10"}'

# Extract and store from a conversation (needs an LLM provider)
curl -X POST http://localhost:6677/v1/ingest \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"agent_id": "00000000-0000-0000-0000-000000000001",
       "conversation": "User: I switched from Postgres to SQLite\nAssistant: Noted."}'

Core

EndpointWhat it does
POST /memoriesStore one memory. Required: agent_id (UUID), memory_type, content. Optional: embedding, user_id, tags, attributes, salience (0.5), confidence (1.0), space_id, valid_from, valid_until. Without an embedding, the server embeds the content when it has an embedder.
GET /memories/{id}One memory. The vector is left out unless you ask with ?fields=embedding.
GET /memoriesA page of memories in creation order. limit (default 50, at most MENTEDB_LIST_MAX_LIMIT, default 1000), offset, tag (narrowed through the tag index before anything loads), include_inactive=1 to also return closed or superseded memories, fields=embedding. Returns memories and next_offset (null on the last page).
PATCH /memories/{id}Update in place, keeping the id. attributes are merged (listed keys set, others kept), tags replace the tags (the tag index follows), valid_until closes the memory at that time or reopens it with null. At least one field. Returns the updated memory.
POST /memories/{id}/supersedeReplace a memory: the new one (content required, optional memory_type, attributes, tags, embedding) is stored with the old one's agent, user and space, the old one is closed and kept for history, and a supersedes edge links them. 409 when the replacement duplicates an existing memory, and then nothing is stored or closed.
DELETE /memories/{id}Forget a memory.
POST /recallRun an MQL query: {"query": "RECALL ..."}. Returns the assembled context, total_tokens and memory_count.
POST /searchVector search: query text (embedded by the server) or an embedding vector, and k (default 10). Returns ids and scores.
POST /edgesLink two memories: source, target, edge_type, optional weight and label.
GET /statsMemory count and uptime.
POST /ingestExtract and store facts from a conversation string for agent_id (UUID, required). Needs an LLM provider, else 503.
POST /process_turnThe full turn pipeline. user_message (required), assistant_response, turn_id, session_id, project_context, agent_id, user_id, store (default true; false runs only recall, pain warnings and the delta, and writes nothing). Returns context, stored, stored_ids, contradictions, facts_extracted and the delta since the previous turn.

Memory

EndpointWhat it does
POST /search/hybridVector plus BM25 keyword search, fused. See below.
POST /contextHeads-up context for a prompt: pinned memories plus the relevant ones, each with a score and a reason (pinned, relevant or mode_rule). Body: query or embedding, max_items (default 10, max 100), max_episodic (default 3), session_id, project, exclude_ids, agent_id, user_id.
POST /recall_for_actionMemories that bear on an action about to happen: procedures, corrections and rules ranked by how strongly they govern it. Body: action text or an embedding, k (default 10, max 100), agent_id, user_id. Read scope is enough.
GET /memories/{id}/historyThe chain of older facts this memory replaced, newest predecessor first. ?depth= up to 64.
GET /memories/{id}/neighborsMemories within depth hops (default 1, max 4, at most 500 memories) and the edges between them. edge_types is a comma separated filter; direction is out, in or both (default).
GET /conflictsCounts of contradicts and supersedes edges, and each pair with both memories.
GET /pinsPinned memories, newest first.
POST /memories/{id}/pinPin a memory (adds scope:always and source:manual).
DELETE /memories/{id}/pinUnpin a memory. The memory is kept.
GET /profileThe user profile memory and the facts it is built from, for ?user_id= and agent_id.
GET /entitiesEntity names with how many memories carry each, plus the names the entity resolver knows.
GET /entities/{name}/memoriesMemories tagged with an entity, after resolving the name to its canonical form.
POST /memories/batchStore up to 1000 memories in one call: {"memories": [...]}, each with the same fields as POST /memories. Every item is validated before any is stored. Returns ids and stored.
GET /memories?session_id=&source=List the memories written in a session or from a source, through the provenance index. Every memory read returns provenance. See Provenance.
POST /memories/{id}/eraseVerified erase of the memory and everything derived from it, returning the receipt. Body (optional): include_sources, verify and the other erase options. 409 when the cascade would pass max_cascade.
POST /sessions/{session_id}/eraseVerified erase of every memory written in a session and everything derived from them, as one erase with one receipt. 403 when an agent bound token names a session holding another agent's memories. See Erase and forgetting.
POST /memory_toolThe backend for Claude's client side memory tool. The body is the tool_use input plus optional agent_id and user_id; the reply is {"content", "is_error"}. See Claude memory tool.
GET /recentThe newest memories, newest first.

Hybrid search

POST /v1/search/hybrid fuses vector similarity with BM25 keyword matching. Send query text (embedded by the server and used for keywords) or an embedding vector. as_of answers as the database stood at that moment, so a fact superseded later still shows; it defaults to now.

JSON
{
  "query": "which database does the project use",
  "k": 10,
  "as_of": 1760000000000000,
  "time_range": [1750000000000000, 1760000000000000],
  "tags": ["project:api"],
  "tags_mode": "and",
  "agent_id": "00000000-0000-0000-0000-000000000001",
  "user_id": "00000000-0000-0000-0000-000000000002",
  "project": "api"
}

Only query or embedding is required. k defaults to 10 (max 200); tags_mode is and (default) or or. The response carries database, as_of, and results: full memories, each with a score.

Three optional fields tune ranking per request. mmr_lambda (0 to 1) sets the diversity weight: 1 turns the pass off, lower values trade relevance for variety so near duplicates do not fill the results. rerank: true reorders the candidates with the built in lexical reranker (needs query text). relevance_first: true picks the top k on relevance alone and only then lets decayed salience order them, so a faded but relevant memory keeps its place.

The memory object

Endpoints that return a memory include id, agent_id, user_id, memory_type, content, created_at, accessed_at, access_count, salience, confidence, space_id, valid_from, valid_until, attributes and tags. The embedding vector is left out unless asked for with ?fields=embedding on GET /memories and GET /memories/{id}. A memory with valid_until set has been closed (superseded, consolidated or patched) and is left out of current results.

Deadlines and errors

Any request may carry x-mentedb-deadline-ms: <n>. Past n milliseconds the server answers 504, and long handlers (paged lists, batch search, consolidation candidates) stop between steps. The header can only shorten the server's own bound, MENTEDB_REQUEST_TIMEOUT_MS. Errors are JSON with one error field. Over the per caller rate limit is 429; a supersede or pin that would duplicate another memory is 409.

Operations

EndpointWhat it does
POST /maintenance/decayAge salience. Pinned memories keep theirs.
POST /maintenance/archiveEvaluate every memory for archival and forget the ones flagged for deletion, capped per run. Reports evaluated, the counts per decision, forgotten and capped.
POST /maintenance/consolidateFold paraphrased duplicates together, then merge clusters of near duplicates. Reports duplicates_merged, clusters_found, clusters_consolidated.
POST /maintenance/sweepThe full sweep the scheduler runs: consolidation, decay, archival, cache eviction.
GET /consolidation_candidatesClusters of near duplicate memories that could be merged, each with its memories and avg_similarity. Read only: nothing changes. Optional min_cluster and similarity.
POST /consolidateMerge exactly the given memories: {"ids": [...]}, at least two. The sources are closed, not deleted, and a new semantic memory links back to them with derived edges.
POST /enrichThe LLM enrichment pipeline over memories not yet enriched: extraction, entity linking, communities, user model. Needs an LLM provider and an embedder, else 503.
POST /documentsLoad a long text as overlapping chunks. See below.
DELETE /documents/{document_id}Forget every chunk of a document.
POST /backupAdmin, or a maintenance token naming the database. Write a backup file of this database and return its manifest. An optional name (for example nightly/2026-10-19) chooses the file name under the database's backup folder.
GET /backupsAdmin. This database's backups, newest first.

POST /v1/documents takes content (required) and optional title, source, agent_id, user_id, tags, memory_type (default semantic), chunk_chars (default 1500, between 100 and 8000) and overlap_chars (default 200, at most half a chunk). Paragraphs stay whole when they fit; longer ones split on sentences. Each chunk is a memory tagged doc:<document_id> with document_id, chunk_index and chunk_count attributes, so search finds the passage and you can fetch its neighbors. The response returns the document_id and the chunk ids.

Outside any database

EndpointWhat it does
GET /v1/healthVersion and uptime. No token needed.
GET /v1/liveLiveness only: touches no database, disk or embedder. No token needed.
GET /v1/readyReadiness: 200 when the default database answers, the data directory takes a write, a probe database takes its lock and the embedder answers; 503 naming the failing checks. ?embedder=skip leaves the embedder out. No token needed.
POST /v1/auth/tokenIssue a token (needs the admin key and a shared secret).
GET, POST /v1/databasesAdmin. List or create named databases.
DELETE /v1/databases/{name}Admin. Delete a named database.
DELETE /v1/db/{db}Delete one named database. Admin, or a maintenance token whose dbs names it.
POST /v1/batch/searchHybrid search across several databases in one call: databases (1 to MENTEDB_BATCH_MAX_DATABASES, default 32), query or embedding, k per database (default 10, max 200), and context: true for each database's heads up context. The query is embedded once. Every database must be readable by the token or nothing is searched (403); one that does not exist is reported under errors and never created.

The server also serves gRPC on 6678, a WebSocket stream at /v1/ws/stream, Prometheus metrics at /metrics and a console at /console, all on the default database. gRPC checks tokens like REST (dbs must admit default; writes need the write scope), and --grpc-port 0 or MENTEDB_GRPC=off turns it off.

See Self-hosted for running the server, and Environment variables for auth and provider config.