Core concepts

Erase and forgetting

Verified erase of one memory or a whole session, with a receipt.

llms.txt

MenteDB has two ways to delete. forget removes a memory from recall, fast, and leaves its bytes on disk until the space is reused. erase removes the memory, everything derived from it, and every copy of their bytes the database holds, then scans the files and returns a receipt you can check. Use erase when a person asks for their data to be deleted.

Which call to use

Cloud callWhat goesBytes on disk
DELETE /api/memories/:idThe memoryStay until the space is reused
POST /api/memories/:id/eraseThe memory and everything derived from itOverwritten, then checked with a scan
POST /api/memories/sessions/:session_id/eraseEvery memory a session wrote and everything derived from themOverwritten, then checked with a scan
POST /api/memories/delete-allEverything the account stored as memoryThe files are deleted

Erase a session

Every memory records the session it was written in (see Provenance). A session erase removes all of them, everything derived from them, and every copy of their bytes, as one erase: one cascade, one scrub, one verification scan and one receipt. A fact drawn from a turn is erased with the turn, and so is a summary that used a session memory, even when it spans other sessions.

POST/api/memories/sessions/:session_id/erase
Cloud. Starts the erase as a job. Answers 200 with the receipt when it finishes quickly, or 202 with a status_url to read until status is no longer running.
include_sourcesbooleanOptional
Also erase memories outside the session that its memories were derived from. Default false.
verifybooleanOptional
Scan the account's files afterwards for the erased bytes. Default true.
curl -X POST https://api.mentedb.com/api/memories/sessions/conv-7/erase \
  -H "Authorization: Bearer $MENTEDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_sources": false, "verify": true}'

# 202: still running, read the job until status is not "running"
curl https://api.mentedb.com/api/memories/jobs/$JOB_ID \
  -H "Authorization: Bearer $MENTEDB_API_KEY"

The finished job carries the receipt. It holds ids and hashes, never content:

JSON
{
  "job_id": "...",
  "kind": "erase_session",
  "status": "done",
  "status_url": "/api/memories/jobs/...",
  "receipt": {
    "session_id": "conv-7",
    "requested": ["6f1c...", "a3d0..."],
    "erased": [
      {"id": "6f1c...", "reason": "requested", "content_sha256": "9b2e...", "embedding_sha256": "40aa..."},
      {"id": "c2e9...", "reason": "derived", "content_sha256": "c71f...", "embedding_sha256": "e5b2..."}
    ],
    "ancestors_kept": [],
    "profiles_to_review": [],
    "verification": {"files_scanned": 14, "residual_found": false, "hits": []}
  }
}
  • verification.residual_found true means the scan still found erased bytes, and hits names the file. Treat it as not finished.
  • ancestors_kept lists sources that were kept and may hold the same text. profiles_to_review lists summaries that may still paraphrase it until their next rebuild.
  • A session with nothing stored answers with an empty receipt and changes nothing, so running it again is safe.
  • The session is looked up in the caller's own account only. Another account is never reached, whatever session id it used.
StatusMeaning
200Done, the receipt is in the body
202Still running, read status_url
400The session id is empty, over 256 bytes or holds control characters, or the body is invalid
409The cascade is over the cap, nothing was changed
429Too many unfinished jobs on this account
503The account is moving between nodes, retry

Older memories have no session

Memories written before provenance existed carry no session and are not matched, even when an old turn has a session:<id> tag. Erase those one at a time by id.

From an AI tool

The MCP server has erase_session (with session_id, and optionally include_sources) and erase_memory. Both are marked destructive. If one answers with status running, call it again with the job_id for the receipt. There is no tool for delete all, on purpose.

Erase one memory

POST/api/memories/:id/erase
Cloud. The memory and everything derived from it, with the same body, job, receipt and statuses as a session erase. A 404 means no such memory in this account.

An erase rewrites the account's snapshots and reads every file of the account, so its time grows with the size of the account, not with what is erased. To remove everything, use delete all rather than an erase per memory.

Self hosted and embedded

The server and the SDKs run the same erase and return the receipt directly, with no job.

# One session (default database; /v1/db/{db}/... for a named one)
curl -X POST localhost:6677/v1/sessions/conv-7/erase -H "Authorization: Bearer $TOKEN"

# One memory and everything derived from it
curl -X POST localhost:6677/v1/memories/$ID/erase -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"include_sources": false, "verify": true}'

On the server, a token bound to an agent may erase a session only when every memory in it is its own; otherwise the call answers 403 and nothing is erased. A cascade over max_cascade answers 409, also with nothing changed. The full field list is in the REST API reference.