SDKs

Python

The Python SDK: the embedded engine, the hosted client and MemoryTool.

llms.txt

Installation

Terminal
pip install mentedb

Requires Python 3.9+. The package includes pre-built wheels for Linux, macOS, and Windows with the Rust core compiled to native extensions via PyO3. On Debian and Ubuntu, pip refuses system-wide installs (PEP 668); use a virtual environment or pipx.

Quick Start

Python
from mentedb import MenteDB

db = MenteDB("./my-data")

# One call per conversation turn, handles everything
result = db.process_turn(
    user_message="I switched from PostgreSQL to SQLite for side projects",
    assistant_response="Got it, I'll suggest SQLite going forward.",
    turn_id=0,
)

# result.context, relevant memories for your prompt
# result.facts_extracted, what was learned this turn
# result.contradiction_count, conflicting beliefs detected
for mem in result.context:
    print(f"[{mem.score:.2f}] {mem.content}")

db.close()

process_turn runs the full cognitive pipeline: embedding, hybrid search, pain signals, fact extraction, contradiction detection, and sleeptime enrichment (when an LLM provider is configured). Fact extraction needs an LLM; set MENTEDB_LLM_PROVIDER and MENTEDB_LLM_API_KEY, or use cloud where it is wired up for you. For low-level control, use store(), search_text(), and recall() individually.

API Methods

MenteDB(data_dir: str = "./mentedb-data", embedding_provider: str | None = None, embedding_api_key: str | None = None, embedding_model: str | None = None)

Open or create a database at the given path. Optionally configure an embedding provider for vector search ('openai', 'bedrock', 'cohere', 'voyage', or local 'candle'); API-key providers use embedding_api_key, while 'bedrock' uses your standard AWS credentials and AWS_REGION. Defaults to a local hash embedder. Supports context manager (with statement).

Returns: MenteDB instance

process_turn(user_message: str, assistant_response: str | None = None, turn_id: int = 0, project_context: str | None = None, agent_id: str | None = None, session_id: str | None = None, user_id: str | None = None)

Run the full conversation-turn pipeline in a single call. Returns a result whose fields are snake_case. This is the primary API, one call per turn. agent_id and user_id are orthogonal owner-scoping axes: pass a stable per-end-user user_id (and optionally agent_id) to keep each user's memory isolated so recall for one owner never returns another's; leave both unset for a single-owner app.

Returns: ProcessTurnResult (context, facts_extracted, contradiction_count, pain_warnings, stored_ids, predicted_topics)

store(content: str, memory_type: str | MemoryType = MemoryType.EPISODIC, embedding: list[float] | None = None, agent_id: str | None = None, tags: list[str] | None = None, created_at: int | None = None, session_id: str | None = None, source: str | None = None, source_ref: str | None = None)

Store a new memory. Returns the UUID of the created memory. Optionally pass a pre-computed embedding, agent ID, tags, a custom created_at as a microsecond timestamp, and the provenance fields session_id, source and source_ref, recorded once on the first write.

Returns: str (UUID)

recall(query: str)

Context-assembled recall using MQL. Returns a text window with relevant memories assembled for LLM consumption.

Returns: RecallResult (text, total_tokens, memory_count)

search_text(query: str, k: int = 10, tags: list[str] | None = None, after: int | None = None, before: int | None = None, session_id: str | None = None, source: str | None = None)

Search memories by text content using the configured embedder. Supports filtering by tags, by time range (after and before are microsecond timestamps), and by provenance: only memories written in session_id or from source.

Returns: list[SearchResult] (id, score)

search(embedding: list[float], k: int = 10)

Vector similarity search over a pre-computed embedding. Use when you already have your own vector; for text queries use search_text().

Returns: list[SearchResult] (id, score)

search_multi(queries: list[str], k: int = 10, tags: list[str] | None = None, before: int | None = None)

Run several queries and merge the results with Reciprocal Rank Fusion, for broader recall across different phrasings of the same need.

Returns: list[SearchResult] (id, score)

search_expanded(query: str, k: int = 10, provider: str | None = None, tags: list[str] | None = None, tags_or: bool = False, before: int | None = None)

Let the engine LLM decompose the query into sub-queries, then run multi-query RRF search. Needs an LLM configured.

Returns: list[SearchResult] (id, score)

ingest(conversation: str, provider: str | None = None, agent_id: str | None = None)

Extract memories from a raw conversation transcript with the LLM pipeline and store them, quality filtered and deduplicated. Needs an LLM configured.

Returns: dict (memories_stored, rejected_low_quality, stored_ids, ...)

extract(conversation: str, provider: str | None = None)

Extract memories from a conversation without storing them. Pair with store_extracted() for staged or parallel workflows.

Returns: list[dict] (content, memory_type, tags, confidence)

store_extracted(memories: list[dict], agent_id: str | None = None)

Store pre-extracted memories (the output of extract()) into the database.

Returns: dict (stored_ids)

get_memory(memory_id: str)

Retrieve a specific memory by ID.

Returns: dict (id, content, memory_type, tags, created_at)

relate(source: str, target: str, edge_type: str | EdgeType = EdgeType.RELATED, weight: float = 1.0, valid_from: int | None = None, valid_until: int | None = None)

Create a typed, weighted relationship between two memories. valid_from and valid_until are optional microsecond timestamps bounding the wall-clock window in which the edge holds; leave both unset for an edge valid for all time.

Returns: None

forget(memory_id: str)

Delete a memory by its ID.

Returns: None

memory_ids_in_session(session_id: str)

Ids of every memory written in a session, read from the provenance index. See Provenance.

Returns: list[str]

erase(memory_id: str, include_sources: bool = False, verify: bool = True)

Verified erase: the memory, everything derived from it, and every copy of their bytes in the data directory, then a scan for residue. include_sources also erases what it was derived from.

Returns: dict (erasure receipt: ids and hashes, never content)

erase_session(session_id: str, include_sources: bool = False, verify: bool = True)

Verified erase of every memory written in a session and everything derived from them, as one erase with one receipt. A session with nothing stored returns an empty receipt.

Returns: dict (erasure receipt with session_id and requested)

run_enrichment(provider: str | None = None, current_turn: int = 0, skip_extraction: bool = False)

Run the full 4-phase sleeptime enrichment pipeline: batch LLM extraction (episodic to semantic and entities), entity linking, community detection, and the always-scoped user model. Pass skip_extraction=True when memories were already extracted during ingest. Needs an LLM: set MENTEDB_LLM_PROVIDER and MENTEDB_LLM_API_KEY.

Returns: dict (enrichment statistics)

needs_enrichment()

Whether enrichment is currently pending.

Returns: bool

build_communities()

Build community summaries for entity clusters, grouping entities by shared categories and generating an LLM summary for each cluster.

Returns: list[str] (community summary memory IDs)

link_entities()

Link entities across sessions by name and embedding similarity.

Returns: dict

entity_memories()

Return all entity memory nodes.

Returns: list (entity memory nodes)

MemoryTool(base_url: str = "http://localhost:6677", token: str | None = None, *, database: str | None = None, agent_id: str | None = None, user_id: str | None = None)

The backend for Claude's client side memory tool, against your server or MenteDB Cloud. Pass MemoryTool.TOOL in tools; results(response.content) turns the model's memory calls into tool_result blocks, execute(input) runs one call, handle(tool_use) returns one block. Standard library only. See Claude memory tool.

Returns: MemoryTool

close()

Flush and close the database. Also runs on __exit__, so a with-statement closes it automatically.

Returns: None