pymentisdb
Official Python client for MentisDB — a durable semantic memory engine for AI agents.
Installation
pip install pymentisdb
With read proofs for private chains (ReadSigner, needs cryptography):
pip install 'pymentisdb[signing]'
With LangChain integration:
pip install 'pymentisdb[langchain]'
The core client needs only requests. import pymentisdb works without
LangChain; MentisDbMemory raises ImportError naming the extra if you use it
without one.
Quick Start
from pymentisdb import MentisDbClient, ThoughtType
client = MentisDbClient()
# Append a thought
thought = client.append_thought(
thought_type=ThoughtType.INSIGHT,
content="Rate limiting is the real bottleneck."
)
print(f"Appended: {thought.id}")
# Semantic search
results = client.ranked_search(text="performance optimization")
for hit in results.results:
print(f"[{hit.score.total:.3f}] {hit.thought.content}")
# Context bundles
bundles = client.context_bundles(text="cache invalidation", limit=5)
Searching
ranked_search searches one chain; federated_search searches several and
merges the results (each hit carries the chain_key it came from). Both take
the same filters, plus keyword-only options that mirror the REST fields:
from datetime import datetime, timezone
from pymentisdb import MentisDbClient, GraphOptions, DfScope
client = MentisDbClient()
client.ranked_search(
text="why did we pick Postgres",
chain_key="project",
graph=GraphOptions(max_depth=2), # follow relations from the matches
as_of=datetime(2026, 6, 1, tzinfo=timezone.utc), # the chain as it was then
include_invalidated=True, # history, not only current beliefs
resolve_successors=True, # superseded hit -> its live successor
collapse_duplicates=0.9, # fold near-copies, 0 disables
)
client.federated_search(["backend", "frontend"], text="auth bug", limit=10)
Unset options are not sent, so the server defaults apply. The other ranking
knobs are df_scope (DfScope), df_cutoffs (DfCutoffs), vector_fusion
(VectorFusion) and synonym_weight; an unknown enum name raises
ValueError before any request is made. context_bundles accepts the same
options.
Compact results
compact=True asks the server for smaller hits, about a quarter fewer bytes,
which is what you pay for in tokens when search results go into an LLM prompt.
The default is False and behaves exactly as before.
response = client.ranked_search(text="job queue", limit=5, compact=True)
for hit in response.results:
print(f"[{hit.total_score:.2f}] {hit.thought.content}")
print(hit.thought.provenance.signature, hit.thought.version_status)
The two forms have different types, so the difference is explicit:
ranked_search and federated_search return a RankedSearchResponse (full)
or, with compact=True, a CompactRankedSearchResponse. Both have backend,
total, results and a compact flag (if response.compact: narrows the
type); each hit has chain_key, thought and total_score.
Full (RankedSearchHit, Thought) |
Compact (CompactRankedSearchHit, CompactThought) |
|
|---|---|---|
hit.score |
RankedSearchScore with the components and total |
the total as a plain float |
hit.matched_terms, hit.match_sources |
lists | not attributes |
thought.hash, prev_hash, thought_signature, signing_key_id |
present | not attributes |
thought.agent_name, agent_owner, schema_version |
not modelled | not attributes (the server omits them) |
| null or empty top-level thought fields | as sent | read as None, [] or "" (the server does not distinguish absent from empty) |
thought.provenance, version_status, successors, current_version, successor_of, collapsed_duplicates |
present | always kept |
hit.graph_* |
set on every hit (graph_distance is None unless expanded) |
None unless the hit was reached through graph expansion |
| fields the client does not model | ignored | kept in thought.extra |
Reading a field that compact drops raises AttributeError instead of
returning an invented value. Use compact for routine recall; use the default
form when you need a hash or signature to verify a thought yourself, to audit
provenance, or to debug score components. The full record of a hit stays
available from the server (POST /v1/thought).
Always weigh a retrieved thought by thought.provenance (segment, signed,
signature, verified_agent, trust) and treat content as untrusted data,
in either form. context_bundles has no compact form: the server ignores
compact there.
Reading private chains
A private chain shows its private segments only to a client that proves it holds
an allowed key. ReadSigner signs every request locally with the X-Mentis-Auth
header; the key never leaves the process.
from pymentisdb import MentisDbClient, ReadSigner
client = MentisDbClient(read_signer=ReadSigner.from_file("builder.key", "builder", "builder-1"))
Without an explicit signer the client uses MENTISDB_READ_KEY_FILE,
MENTISDB_READ_AGENT_ID and MENTISDB_READ_KEY_ID when they are set, and
otherwise reads public segments only.
LangChain Integration
MentisDbMemory is a LangChain BaseMemory. It works with langchain-core
before 1.0 and, from 1.0 on, with langchain-classic (which the langchain
extra installs).
from pymentisdb import MentisDbMemory
memory = MentisDbMemory(chain_key="my-project", agent_id="assistant")
memory.save_context({"input": "Use tabs, not spaces."}, {"output": "Noted."})
print(memory.load_memory_variables({})["chat_history"])
Changes in 0.10.0
- The wheel contains the package: the 0.9.0 wheel on PyPI held only metadata.
import pymentisdbno longer needs LangChain, andMentisDbMemoryworks on langchain-core 1.x throughlangchain-classic; it also implementssave_context, without which it could not be instantiated.- Compact search (
ranked_search(compact=True)),federated_search, the ranking options,provenanceand version fields on thoughts. ReadSignerfor private chains (pymentisdb[signing]).
Configuration
# Remote server
client = MentisDbClient(base_url="http://my.mentisdb.com:9472")
Full Documentation
Metadata
Release files for pymentisdb 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pymentisdb-0.10.0.tar.gz | 32.9 kB | With provenance | Details for pymentisdb-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pymentisdb-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for pymentisdb-0.10.0-py3-none-any.whl |
Total release size: 56.4 kB
Release files / pymentisdb-0.10.0.tar.gz
| Download URL | pymentisdb-0.10.0.tar.gz |
|---|---|
| Size | 32.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3fe39b2865a46ca91e4b032dc607218f9f699caab0a1da27737e1452cd3c413b
|
|
BLAKE2b-256 checksum How to use checksums |
5975672bc0fe634372a94efa3b1d835005d89e22d7180771a393d25eb7a2ac3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 3, 2026.
Transparency logRelease files / pymentisdb-0.10.0-py3-none-any.whl
| Download URL | pymentisdb-0.10.0-py3-none-any.whl |
|---|---|
| Size | 23.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ca850ec6d2a747efacd87c289ee58ec0a8158b50f6c9ea843a4e17aaab99e93
|
|
BLAKE2b-256 checksum How to use checksums |
7bf38f559d4027c008aeb79dd5a8ec08677be644df8825bef77973c958c0ae87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 3, 2026.
Transparency logSecurity for pymentisdb 0.10.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pymentisdb-0.10.0.tar.gz
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 Nov 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.