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:
Newer release available (0.32.2)

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.1-cp39-abi3-win_amd64.whl (6.0 MB view details)

Uploaded CPython 3.9+Windows x86-64

mentedb-0.32.1-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.1-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.1-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.1-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: mentedb-0.32.1-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.1-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 34ba0e9ce63a52d9761af6bbb2b93b7073c51a09e0e75bd28e6484f6dd88fa42
MD5 758f353a66cfa33139a84b15210ccfe0
BLAKE2b-256 fa6ffb972f58593e6cd1abc49920a9ba1c7b4d19966c76511b95af51b1ff5a72

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.1-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.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mentedb-0.32.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9fa8b765967dba32507467841ed1830c93945a9dd607afd9ac30a03433d2b3ad
MD5 e6e8acfee244c4beb2a0841143c8f4d9
BLAKE2b-256 f6c920c53d5194e68baffd76b13cedcfb7c95c04f0c6d2b3af4ea8920373ae4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.1-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.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mentedb-0.32.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 fe8be75a3332dc86b0f70ff88ce6f142b67519feb8641716a1bc52b739fa3449
MD5 8b185612b6a291b5b0d9df62dac2ebf6
BLAKE2b-256 73bbe0fb1ffe8061fc5b4cf8405a52d00dcf363ac1a656ead3e6bed8dddd383a

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.1-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.1-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mentedb-0.32.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5b61d283d2d2347b2d6335e3818913f7328e2d2367a6aacc2eb52d4967312361
MD5 29581ed6c57cb4e8ec2e845d3282ac46
BLAKE2b-256 8129adf3856547076d65bf6af497d505fbd28815245956c64d72d6bcc5574821

See more details on using hashes here.

Provenance

The following attestation bundles were made for mentedb-0.32.1-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

0.32.2

4 files

This release

0.32.1 This release

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