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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nambok from gravatar.com nambok

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.9

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mentedb-0.32.2-cp39-abi3-win_amd64.whl (6.0 MB view details)

Uploaded CPython 3.9+Windows x86-64

mentedb-0.32.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (9.7 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

mentedb-0.32.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (9.8 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

mentedb-0.32.2-cp39-abi3-macosx_11_0_arm64.whl (6.2 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file mentedb-0.32.2-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: mentedb-0.32.2-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 6.0 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for mentedb-0.32.2-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 699dd289c8bd9cb4731742a6d219d5d052a467fd8fd60a0841ffa1c60e3971ef
MD5 5cf67119d5f72b312d653501212de84e
BLAKE2b-256 22784405ca4077cf8ba3d62d294b7b05e93909761fd6f767cfb24b489fcab28a

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.2-cp39-abi3-win_amd64.whl:

Publisher: publish-sdks.yml on nambok/mentedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mentedb-0.32.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mentedb-0.32.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ce8ededf59cfde12758114de8b68e76a97bda23a9bb47ab2ca2c7938c7498796
MD5 d7bef370bdd06e5ef227873fbe3966b3
BLAKE2b-256 7acc75a48df54b02f3f2fd038ef5c29155c5fdb603222018b6fe196165e2f569

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-sdks.yml on nambok/mentedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mentedb-0.32.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mentedb-0.32.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a0df81a7d64fea208b9f321bf4870c5e42e246ff57d1253d58876acfe37ca827
MD5 34e588ca893873c8a285f47f557a1ed2
BLAKE2b-256 49ba24bfae740a74f1f881cac33a3872350a480f603c2e7bc8b8f189a0e2efcd

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish-sdks.yml on nambok/mentedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mentedb-0.32.2-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mentedb-0.32.2-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 910308cab3aab8a5e55c796ea4a2e692fc55b52d58630d5ea27cb2af7d2c26a9
MD5 5de9591316fde9264c398c3610d66b13
BLAKE2b-256 e99d19316d0c6f6aaef1fcaa1ef27d44fab08452b05457693173d46d6ced388b

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.2-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: publish-sdks.yml on nambok/mentedb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.32.2 This release

4 files

0.32.1

4 files

0.32.0

4 files

0.31.0

4 files

0.30.0

4 files

0.29.0

4 files

0.28.0

4 files

0.27.3

4 files

0.27.2

4 files

0.27.1

4 files

0.27.0

4 files

0.26.0

4 files

0.25.0

4 files

0.24.6

4 files

0.24.5

4 files

0.24.4

4 files

0.24.3

4 files

0.21.1

4 files

0.21.0

4 files

0.20.4

4 files

0.20.3

4 files

0.20.2

4 files

0.20.1

4 files

0.20.0

4 files

0.19.0

4 files

0.18.0

4 files

0.17.11

4 files

0.17.10

4 files

0.17.9

4 files

0.17.8

4 files

0.17.7

4 files

0.17.6

4 files

0.17.5

4 files

0.17.4

4 files

0.17.3

4 files

0.17.2

4 files

0.17.1

4 files

0.17.0

4 files

0.16.1

4 files

0.16.0

4 files

0.15.1

4 files

0.15.0

4 files

0.14.7

4 files

0.14.6

4 files

0.14.5

4 files

0.14.4

4 files

0.14.3

4 files

0.14.1

4 files

0.14.0

4 files

0.13.1

4 files

0.13.0

4 files

0.12.6

4 files

0.12.4

4 files

0.12.3

4 files

0.12.2

4 files

0.12.1

4 files

0.12.0

4 files

0.11.14

4 files

0.11.13

4 files

0.11.12

4 files

0.11.11

4 files

0.11.10

4 files

0.11.7

4 files

0.11.6

4 files

0.11.5

4 files

0.11.4

4 files

0.11.3

4 files

0.11.2

4 files

0.11.1

4 files

0.11.0

4 files

0.10.8

4 files

0.10.5

4 files

0.10.4

3 files

0.10.0

3 files

0.9.2

3 files

0.9.1

3 files

0.9.0

3 files

0.8.2

3 files

0.8.1

3 files

0.8.0

3 files

0.7.0

3 files

0.3.1

3 files

0.2.10

3 files

0.2.9

3 files

0.2.7

3 files

0.2.5

3 files

0.2.1

3 files

0.1.0

3 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page