Core concepts
Provenance
Every memory records its session, source, writer and time when it is first written.
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
| Field | Meaning |
|---|---|
session_id | The session the memory was written in, when the writer named one. |
source | The kind of source: chat, file, api, mcp, import, derived or unspecified. |
source_ref | A reference into the source: a file path, a URL, a message id. |
written_by | The agent that wrote it. Shared memories carry the nil UUID. |
written_at | When it was first written, in microseconds since the Unix epoch. Separate from created_at, which an import may set to an older time. |
derived_from | For 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 path | source | session_id |
|---|---|---|
process_turn, the turn itself | chat | The turn's session_id |
| Facts drawn from a turn | derived | The turn's session |
Cloud POST /api/memories, server POST /v1/memories, SDK store | api | From the request |
MCP store_memory and store_memories | mcp | The session_id argument |
The memory tool, POST /v1/memory_tool | file | From the request; source_ref is the file path |
| Agent file ingestion | file | None |
| Enrichment, consolidation, entity and community summaries | derived | The 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_atReading 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.
{
"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
/api/memories?session_id=conv-7&source=mcp/api/memories/sessionscurl "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
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.