Module hosting 

Hosting endpoints and middleware: paged lists, in place updates, scoped drops, batch search, deadlines and the enrichment pool. Endpoints and middleware for running the server as a shared, multi tenant service:

Per database (mounted under /v1 and /v1/db/{db}):

• GET /memories: a paged, token scoped list, narrowed by tag through the bitmap index, in a stable order.
• PATCH /memories/{id}: update attributes, tags and valid_until in place, keeping the id.
• POST /memories/{id}/supersede: replace a memory with a new one, closing the old one and linking the two with a Supersedes edge.
• POST /recall_for_action: memories that bear on an action about to happen.
• GET /consolidation_candidates: clusters of near duplicates (read only).
• POST /consolidate: merge exactly the given memories.

Global:

• DELETE /v1/db/{db}: drop a database (admin, or a maintenance token for it).
• POST /v1/batch/search: one query across several databases.
• GET /v1/live: liveness, touching nothing.

Middleware: request deadlines (x-mentedb-deadline-ms and MENTEDB_REQUEST_TIMEOUT_MS). Also the bounded enrichment worker pool.

Structs

Deadline

When the current request must be answered by. Long handlers check it between steps and stop with 504 once it has passed.

HostingConfig

Settings for the hosting endpoints and middleware.

Constants

DEADLINE_HEADER

Header carrying the caller’s budget for a request, in milliseconds.

Functions

authorize_maintenance

Allow a database maintenance operation (drop, backup) on name: the admin key, an admin token, or a token with the maintenance scope whose dbs names the database. Without any of these the admin key check’s answer stands (401 with no key, 403 with a wrong one).

batch_search

Hybrid search across several databases in one call, the query embedded once. Body: databases (names), query and/or embedding, k, context (also return each database’s heads up context), max_items (context size), agent_id, user_id. Every database must be readable by the token, or the whole request is refused. A database that does not exist is reported under errors without stopping the others.

consolidate

Merge exactly the given memories. Body: ids (two or more). The sources are closed, not deleted, and a new semantic memory links back to them.

consolidation_candidates

Clusters of near duplicate memories that could be merged. Read only. Query: min_cluster (default from the server’s consolidation settings), similarity (0 to 1). A token bound to an agent sees only clusters made entirely of memories it may see.

deadline_middleware

Bound every request by the smaller of the server’s request timeout (the middleware state) and the caller’s x-mentedb-deadline-ms. Past it the request is answered with 504; the handler sees the Deadline and its long loops stop early. A malformed header is a 400.

drop_database

Close and permanently delete a named database.

global_routes

Routes outside any one database.

hosting_config

The hosting settings, read from the environment once.

list_memories

A page of the caller’s memories. Query: limit, offset, tag, include_inactive (0 or 1), fields=embedding. A token bound to an agent sees its own memories and shared ones owned by no agent.

live

Liveness: the process answers. Touches no database, disk or embedder, so a slow dependency never gets a healthy process restarted. Point liveness probes here and readiness probes at /v1/ready.

patch_memory

Update a memory in place. Body: attributes (merged), tags (replaces), valid_until (microseconds, or null to clear). The id is kept.

recall_for_action

Memories that bear on an action about to happen. Body: action (text), optional embedding (else the action is embedded), k, agent_id, user_id.

routes

Routes on one database that are new paths. GET /memories and PATCH /memories/{id} are added to the existing paths in routes.rs.

run_on_enrichment_pool

Run job on the enrichment pool, waiting for a free slot first, and return its output.

supersede_memory

Replace a memory. Body: content (required), memory_type (defaults to the old memory’s), attributes, tags, embedding. The new memory keeps the old one’s owners and space; the old one is closed now and linked from the new one by a Supersedes edge.