MenteDB Python SDK
Python bindings for MenteDB, the mind database for AI agents. Built with PyO3 and maturin for native Rust performance from Python.
Installation
From PyPI
pip install mentedb
Prebuilt wheels are published for macOS arm64, Linux x86_64 and aarch64, and Windows x86_64 (Python 3.9+).
From source (development)
cd sdks/python
pip install maturin
maturin develop
On Debian and Ubuntu systems pip refuses system wide installs (PEP 668). Use a virtual environment or pipx:
python3 -m venv .venv && .venv/bin/pip install mentedb
# or: pipx install mentedb
Quick start
from mentedb import MenteDB, MemoryType, EdgeType
with MenteDB("./agent-memory") as db:
# process_turn — the primary API, one call does everything
result = db.process_turn(
user_message="The deployment failed because the config was missing",
assistant_response="I'll check the config setup.",
turn_id=0,
)
# result.context — relevant memories for your prompt
# result.facts_extracted — what was learned this turn
# result.contradiction_count — conflicting beliefs detected
# Optional kwargs: project_context, agent_id, session_id (tags stored
# turns so injection recall can exclude the requesting session), user_id
# (agent_id and user_id must be UUID strings)
# Enrichment (LLM fact extraction, entity linking, community summaries,
# user profile) is a separate call; see "Sleeptime enrichment" below.
# Or use low-level APIs directly:
# Store a memory
mid = db.store(
"The deployment failed because the config was missing",
memory_type=MemoryType.EPISODIC,
tags=["deployment", "config"],
)
# Recall memories with MQL
result = db.recall("RECALL tag:deployment LIMIT 5")
print(result.text)
# Vector similarity search
hits = db.search(embedding=[0.1] * 384, k=5)
for hit in hits:
print(f"{hit.id}: {hit.score:.4f}")
# Relate memories
mid2 = db.store("Always validate config before deploy", memory_type=MemoryType.PROCEDURAL)
db.relate(mid, mid2, edge_type=EdgeType.CAUSED)
# Forget a memory
db.forget(mid)
MenteDB Cloud (hosted)
Prefer a managed API with no engine to run? Use MenteDBClient with an mdb_
key from app.mentedb.com. The verbs mirror the
embedded client, so only the constructor changes.
from mentedb import MenteDBClient
client = MenteDBClient(api_key="mdb_...")
# Turn 0: tell it something.
client.process_turn("I switched from Postgres to SQLite for side projects", "Noted.", 0)
# Turn 1: it remembers.
result = client.process_turn("what database am I using for side projects?", "", 1)
for memory in result.context:
print(memory.content)
# Also available: client.search(...), client.store(...),
# client.store_multimodal(data, media_type=...), client.forget(memory_id)
MenteDBClient is pure standard library (no extra dependencies) and talks to
https://api.mentedb.com. process_turn uses the REST endpoint, while store,
search, store_multimodal, and forget use the hosted MCP tools.
Cognitive features
The SDK also exposes MenteDB cognitive subsystems for real time stream monitoring, conversation trajectory tracking, and pain signal management.
Sleeptime Enrichment
The embedded SDK does not enrich on its own. process_turn marks when
enrichment is due; check db.needs_enrichment() and call
db.run_enrichment() (for example from a background worker). The pipeline
extracts semantic facts, links and deduplicates entities, groups them into
communities with summaries, and builds a user profile, all of which feed later
process_turn context retrieval.
Requires an LLM provider: set MENTEDB_LLM_PROVIDER (openai, anthropic or
ollama) and MENTEDB_LLM_API_KEY. Without them the engine works normally
and run_enrichment raises an error.
Cognitive subsystems
import uuid
from mentedb._mentedb_python import CognitionStream, TrajectoryTracker, PainRegistry
# Stream monitoring (fact ids must be UUID strings)
fact_id = str(uuid.uuid4())
stream = CognitionStream(buffer_size=500)
stream.feed_token("The")
stream.feed_token(" sky")
alerts = stream.check_alerts([(fact_id, "the sky is blue")])
# Trajectory tracking
tracker = TrajectoryTracker(max_turns=50)
tracker.record_turn("deployment", "investigating", ["which env?"])
context = tracker.get_resume_context()
# Pain registry
pain = PainRegistry(max_warnings=3)
pain.record_pain(str(uuid.uuid4()), 0.8, ["timeout", "deploy"], "deploy timed out")
warnings = pain.check_triggers(["deploy"])
API reference
MenteDB
| Method | Description |
|---|---|
process_turn(user_message, assistant_response, turn_id, project_context, agent_id, session_id, user_id) |
Primary API. Process a conversation turn through the full cognitive pipeline |
store(content, memory_type, embedding, agent_id, tags, created_at) |
Store a memory, returns its UUID |
recall(query) |
Recall memories using MQL |
search(embedding, k) |
Vector similarity search |
search_text(query, k, tags, after, before) |
Similarity search with the configured embedding provider |
get_memory(memory_id) |
Fetch one memory as a dict |
relate(source, target, edge_type, weight, valid_from, valid_until) |
Add a relationship |
forget(memory_id) |
Remove a memory |
needs_enrichment() / run_enrichment(provider, current_turn) |
Check for and run sleeptime enrichment (needs an LLM) |
close() |
Flush and close the database |
Only one MenteDB instance can hold a data directory at a time; opening the
same directory again raises a "locked by another process" error.
Types
MemoryType: episodic, semantic, procedural, anti_pattern, reasoning, correction
EdgeType: caused, before, related, contradicts, supports, supersedes, derived, part_of
License
Apache 2.0. See the repository root LICENSE file for details.
1 maintainer
Metadata
1 maintainer
Release files for mentedb 0.42.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| mentedb-0.42.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| mentedb-0.42.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| mentedb-0.42.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| mentedb-0.42.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 32.3 MB
Release files / mentedb-0.42.0-cp39-abi3-win_amd64.whl
| Download URL | mentedb-0.42.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 6.1 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
516c7cd7bf85eba06479223eb3c17ea8c3fbfa1326fafe3e955a6c1759efa088
|
|
BLAKE2b-256 checksum How to use checksums |
661ef437cd51e2130b1f53e9862b6f3a4720254278a5c716fcfbf1a99b8ac433
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / mentedb-0.42.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | mentedb-0.42.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3bad3550e5002d1eea77f6ef3126253d4b1cd955a5239d56086e0e54549340e4
|
|
BLAKE2b-256 checksum How to use checksums |
c63eed7a8575e6383f7108ff31069891e92966259a7ded9dfc2cb97c10889f34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / mentedb-0.42.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | mentedb-0.42.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 10.0 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
9a9c7cbdd351851418b1f1ff00997dac3967540cfc3a50dfd3b7d412317d1cb2
|
|
BLAKE2b-256 checksum How to use checksums |
795b60571d81f2c4c447bc893c806746476d482072b6d3e1fd697304de55d3e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / mentedb-0.42.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | mentedb-0.42.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 6.4 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
84748e69debc8633cb25246b9c887466fafd778f6efce018fa52ee9a505dc48e
|
|
BLAKE2b-256 checksum How to use checksums |
24b1029e37e2c85169a9546fd8a1f4e569bc7652663c9449043546a2af42bb50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency log
