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 source (development)
cd sdks/python
pip install maturin
maturin develop
From PyPI (once published)
pip install mentedb
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
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)
# Sleeptime enrichment runs automatically after process_turn:
# - Extracts semantic facts from conversations
# - Links and deduplicates entities
# - Builds community summaries and user profile
# Requires LLM config: MENTEDB_OPENAI_API_KEY or MENTEDB_ANTHROPIC_API_KEY
# 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
MenteDB automatically enriches memories in the background after process_turn. The pipeline extracts semantic facts, links and deduplicates entities, groups them into communities with summaries, and builds a user profile — all feeding back into future process_turn context retrieval.
Requires an LLM provider: set MENTEDB_OPENAI_API_KEY or MENTEDB_ANTHROPIC_API_KEY. Without one, the engine works normally — enrichment just doesn't run.
Cognitive subsystems
from mentedb._mentedb_python import CognitionStream, TrajectoryTracker, PainRegistry
# Stream monitoring
stream = CognitionStream(buffer_size=500)
stream.feed_token("The")
stream.feed_token(" sky")
alerts = stream.check_alerts([("some-uuid", "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("some-uuid", 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) |
Primary API. Process a conversation turn through the full cognitive pipeline |
store(content, memory_type, embedding, agent_id, tags) |
Store a memory, returns its UUID |
recall(query) |
Recall memories using MQL |
search(embedding, k) |
Vector similarity search |
relate(source, target, edge_type, weight) |
Add a relationship |
forget(memory_id) |
Remove a memory |
close() |
Flush and close the database |
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.39.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.39.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| mentedb-0.39.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.39.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| mentedb-0.39.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 32.0 MB
Release files / mentedb-0.39.0-cp39-abi3-win_amd64.whl
| Download URL | mentedb-0.39.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 |
87ad643c568225f5f66acfdc57c463d1bf09ec188ad66a8eda1a28e26acdf6a7
|
|
BLAKE2b-256 checksum How to use checksums |
b1c3750ea1613f8da4df4b8ce5c8d765bcc0aa28eac0f6fed16c56fcca4aea9a
|
| 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 18, 2026.
Transparency logRelease files / mentedb-0.39.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | mentedb-0.39.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.8 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
973ea21dbec5249e3096d67a2269dfbc7fd9c4bf7abf6067047fde775d88e7ff
|
|
BLAKE2b-256 checksum How to use checksums |
5f0cc54c388e27a44e3a25bbb98626e08f4c9c07b932581600d9084696fe2280
|
| 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 18, 2026.
Transparency logRelease files / mentedb-0.39.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | mentedb-0.39.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 9.9 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
d3394cd66875d8c329abb34b1d643e0b137b3295ae7506b34aec9b7490d020f9
|
|
BLAKE2b-256 checksum How to use checksums |
7c0518b6b90f4d06b9bfd45db99b5e60a7bbbd7a2113d3705cce582138f9ac15
|
| 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 18, 2026.
Transparency logRelease files / mentedb-0.39.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | mentedb-0.39.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 6.3 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
19e9d6c5c5276797dae3322800f17909969af7e2d6a493e32ffcfef7c6816cb6
|
|
BLAKE2b-256 checksum How to use checksums |
15f2430a8c6460cf813f717bdb444b358508b82099fd370186c58bfaad2ca48c
|
| 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 18, 2026.
Transparency log
