SDKs
Python
The Python SDK: the embedded engine, the hosted client and MemoryTool.
Installation
pip install mentedbRequires 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
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