Core concepts

Provenance

Every memory records its session, source, writer and time when it is first written.

llms.txt

Every memory records where it came from at the moment it is first written, and that record never changes afterwards. An edit, a pin, a rename or a second store of the same id keeps it. With it you can see where a fact came from, list what a conversation wrote, and forget a whole session in one call.

What is recorded

FieldMeaning
session_idThe session the memory was written in, when the writer named one.
sourceThe kind of source: chat, file, api, mcp, import, derived or unspecified.
source_refA reference into the source: a file path, a URL, a message id.
written_byThe agent that wrote it. Shared memories carry the nil UUID.
written_atWhen it was first written, in microseconds since the Unix epoch. Separate from created_at, which an import may set to an older time.
derived_fromFor a derived memory, the ids of the memories it was made from.

A writer names at most the session and the source reference. The server sets written_by and written_at, and on the cloud the source is fixed by the path a write takes, so a client cannot claim another one. A session id is at most 256 bytes and a source reference at most 1024, with no control characters.

Who records what

Write pathsourcesession_id
process_turn, the turn itselfchatThe turn's session_id
Facts drawn from a turnderivedThe turn's session
Cloud POST /api/memories, server POST /v1/memories, SDK storeapiFrom the request
MCP store_memory and store_memoriesmcpThe session_id argument
The memory tool, POST /v1/memory_toolfileFrom the request; source_ref is the file path
Agent file ingestionfileNone
Enrichment, consolidation, entity and community summariesderivedThe session every origin shares, else none

A derived memory joins a session only when every memory it was made from is in that same session. A summary across two conversations belongs to neither.

Write with provenance

Pass a session_id on every turn and every store. It is the key for listing and erasing a conversation later.

from mentedb import MenteDB

db = MenteDB("./agent-memory")

# A turn records source "chat" and its session.
db.process_turn("I moved to Lisbon", "Noted.", turn_id=0, session_id="conv-7")

# A direct store names the session and a reference into the source.
memory_id = db.store("Prefers tabs over spaces", session_id="conv-7", source_ref="msg-42")

memory = db.get_memory(memory_id)
print(memory["provenance"])  # session_id, source, source_ref, written_by, written_at

Reading it

Every memory read returns provenance: the REST memory endpoints, the query console, and the MCP search_memories and list_memories results. A memory written before provenance existed returns "provenance": null. Context injected into the prompt by process_turn leaves it out to stay small; look a memory up by id to see it.

JSON
{
  "memory_id": "6f1c...",
  "content": "Prefers tabs over spaces",
  "provenance": {
    "session_id": "conv-7",
    "source": "mcp",
    "source_ref": "msg-42",
    "written_by": "00000000-0000-0000-0000-000000000000",
    "written_at": "1793845123000000",
    "derived_from": []
  }
}

The cloud API returns written_at as a string, like created_at. The self hosted server returns it as a number.

Filtering by session and source

Session and source are indexed, so a filter loads only the memories it matches and never scans. A search inside a session is narrowed before it runs, so a small session searches only its own memories instead of being cut out of a global top k.

Cloud

GET/api/memories?session_id=conv-7&source=mcp
Lists the memories written in a session or from a source. Works with every other filter, sort and cursor of the memory list.
GET/api/memories/sessions
Lists the sessions the account's memories were written in, each with how many memories it holds, read from the provenance index.
Terminal
curl "https://api.mentedb.com/api/memories/sessions" \
  -H "Authorization: Bearer $MENTEDB_API_KEY"
# {"sessions": [{"session_id": "conv-7", "memories": 42}, ...]}

Over MCP, search_memories and list_memories take session_id and source arguments.

Self hosted server

Terminal
curl "localhost:6677/v1/memories?session_id=conv-7&source=chat" -H "Authorization: Bearer $TOKEN"

curl -X POST localhost:6677/v1/search/hybrid -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "trip plans", "session_id": "conv-7"}'

SDKs and MQL

ids = db.memory_ids_in_session("conv-7")
hits = db.search_text("trip plans", k=10, session_id="conv-7", source="chat")

In MQL, session and source take =, != or IN, compared exactly as written. A source name the engine does not know matches nothing.

Next

With sessions recorded, Erase and forgetting removes everything a conversation wrote, and everything derived from it, with one verified receipt.