mnestic (Python)

Embedded graph + vector + full-text database with Datalog queries — a maintained fork of CozoDB, tuned as a substrate for agentic memory. This package is the in-process Python binding (no server required).

mnestic is not the official CozoDB and is not affiliated with or endorsed by its original authors. All credit for the original design belongs to Ziyang Hu and the Cozo Project Authors. See the fork repository for provenance and licensing.

pip install mnestic

from mnestic import CozoDbPy

db = CozoDbPy("mem", "", "{}")  # engines: "mem", "sqlite" (file path), "rocksdb" (dir path)
db.run_script("?[x] <- [[1],[2],[3]]", {}, False)

# One-call hybrid retrieval (HNSW + full-text fused with Reciprocal Rank Fusion),
# over a relation that has an HNSW index and an FTS index:
hits = db.hybrid_search({
    "relation": "docs",
    "vector_index": "vec", "query_vector": [0.1, 0.9], "vector_k": 5,
    "fts_index": "fts", "query_text": "vector search", "fts_k": 5,
})
# -> {"headers": ["id", "score"], "rows": [["d3", 0.033], ...], "next": None}

# Pass "detailed": True for per-leg contributions — one row per (item, leg)
# with the within-leg rank the fusion used and the leg's raw score:
# headers ["id","score","list_id","leg_rank","leg_score"]

The "rocksdb" persistent backend now ships in the published wheel — CozoDbPy("rocksdb", "./my.db", "{}") works straight from pip install mnestic. The source distribution ships compact, RDF boundary I/O, and host-controlled Parquet/Arrow import, but no RocksDB sources, so the persistent engine remains wheel-only.

Published wheels and source builds expose atomic local-file copy-in through import_columnar_file. The target relation must already exist; the format is explicit and the call releases Python's GIL while decoding and committing:

report = db.import_columnar_file(
    "events",
    "events.parquet",
    format="parquet",  # or arrow_ipc_file / arrow_ipc_stream
    columns={"event_id": "id"},
    batch_rows=8192,
    max_rows=1_000_000,
)

Upgrade note (0.10.6): a persistent database whose relation catalogs were last written by a build older than 0.10.0 could fail to open with Cannot deserialize relation metadata from bytes after upgrading to 0.10.0–0.10.5. 0.10.6 fixes this — legacy catalogs open again with no migration, so upgrade to 0.10.6 if you carry a pre-0.10.0 database.

run_script takes an optional timeout= — a per-query wall-clock budget in seconds; on expiry the query raises an eval::timeout error. db.set_default_query_timeout(secs) sets a Db-wide default and db.default_query_timeout() reads it back; the effective budget for a query is the minimum of that default and any per-call timeout.

RDF at the boundary — and what it means for the wheel's trust posture

The wheel ships the rdf-io engine feature: RdfReader reads Turtle, N-Triples, N-Quads and TriG into a fixed 6-column relational shape (subject, predicate, object, graph, language_tag, datatype) straight from CozoScript, and IRI helper functions (iri_valid, iri_resolve, curie_expand, curie_compact) handle boundary identity:

db.run_script("""
    triples[s, p, o, g, lang, dt] <~ RdfReader(url: 'file://./data.ttl')
    ?[s, o] := triples[s, 'http://xmlns.com/foaf/0.1/knows', o, _, _, _]
""", {}, True)

Read this before running untrusted CozoScript. rdf-io implies the engine's data-import trust gate, so this wheel — deliberately reversing the 0.14.0 posture — again registers script-controlled readers: RdfReader, CsvReader and JsonReader can read any file the process can read, and because the wheel also compiles HTTP support (requests), a script can fetch non-file:// URLs. Only run CozoScript from callers you trust with those capabilities, or build the binding from source without the rdf-io feature for a locked-down deployment.

New in 0.18.0

This release corrects string decoding, nested JSON conversion and single-term FTS prefixes. Review these result changes before upgrading:

BREAKING (results): double-quoted "a\nb" now contains a newline. Use _"a\nb"_ for a literal backslash or bind parameters. Literal edge whitespace and comments are preserved; trim explicitly when intended. Raw fences require adjacent matching underscores. Audit stored-query bodies as well as scripts.
BREAKING (results): nested UUIDs become strings, bytes become base64 strings, and scalar infinities become "INFINITY" / "NEGATIVE_INFINITY", including new Json-column writes and to_string. Stored JSON stays unchanged; migrate only known typed fields or adapt consumers. Old infinity-derived nulls are irreversible.
FTS prefixes apply configured lowercase and ASCII-folding filters: Di* matches Diwank on a lowercase index without rebuilding it. Prefixes match indexed terms, including stems; exact terms retain the full analyzer pipeline. Use an index without those filters when case/accent distinctions must be preserved.
Integer FTS boosts such as Di*^3 no longer panic.

There is no storage-format migration or bridge release. Python native conversions remain unchanged; \uXXXX escapes remain BMP-only (bind parameters or use literal non-BMP text). The temporary string migration warning is scheduled for removal in 0.19.0.

Full upgrade guidance is in the fork changelog.

For idiomatic LangChain / LlamaIndex usage, install the integration packages (langchain-mnestic, llama-index-vector-stores-mnestic).

The query language (CozoScript / Datalog) and engine semantics follow CozoDB; see the upstream documentation and the fork changelog.

License

Download files

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

Source Distribution

mnestic-0.18.0.tar.gz (780.8 kB view details)

Uploaded Sep 5, 2026 Source

Built Distributions

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

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mnestic-0.18.0-cp37-abi3-win_amd64.whl (12.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.7+Windows x86-64

mnestic-0.18.0-cp37-abi3-manylinux_2_28_x86_64.whl (15.6 MB view details)

Uploaded Sep 5, 2026 CPython 3.7+manylinux: glibc 2.28+ x86-64

mnestic-0.18.0-cp37-abi3-manylinux_2_28_aarch64.whl (15.5 MB view details)

Uploaded Sep 5, 2026 CPython 3.7+manylinux: glibc 2.28+ ARM64

mnestic-0.18.0-cp37-abi3-macosx_11_0_x86_64.whl (13.7 MB view details)

Uploaded Sep 5, 2026 CPython 3.7+macOS 11.0+ x86-64

mnestic-0.18.0-cp37-abi3-macosx_11_0_arm64.whl (12.4 MB view details)

Uploaded Sep 5, 2026 CPython 3.7+macOS 11.0+ ARM64

File details

Details for the file mnestic-0.18.0.tar.gz.

File metadata

Download URL: mnestic-0.18.0.tar.gz
Upload date: Sep 5, 2026
Size: 780.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mnestic-0.18.0.tar.gz
Algorithm	Hash digest
SHA256	`4021b722509dd75088918679bc9cdc2324114225925c97eae9e231ac9871b024`
MD5	`b27883cf2e41d9fa86b55259c2ae9f9a`
BLAKE2b-256	`7d0d1085428653a2602efdc993103da43cc1fb4ddf941ed31bf2451379be80d9`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.18.0.tar.gz:

Publisher: python-publish.yml on shuruheel/mnestic

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mnestic-0.18.0.tar.gz
- Subject digest: 4021b722509dd75088918679bc9cdc2324114225925c97eae9e231ac9871b024
- Sigstore transparency entry: 2732550056
- Sigstore integration time: Sep 5, 2026
Source repository:
- Permalink: shuruheel/mnestic@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Branch / Tag: refs/tags/py-v0.18.0
- Owner: https://github.com/shuruheel
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Trigger Event: push

File details

Details for the file mnestic-0.18.0-cp37-abi3-win_amd64.whl.

File metadata

Download URL: mnestic-0.18.0-cp37-abi3-win_amd64.whl
Upload date: Sep 5, 2026
Size: 12.6 MB
Tags: CPython 3.7+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mnestic-0.18.0-cp37-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`9d9e9e85bdb36c23757f7ec1fe56b8ba402df9d8fce3fe576806ada6da4b5f32`
MD5	`fd6e09485c14e67429354132e39fa777`
BLAKE2b-256	`c0b6824ec5403bc5be873459a3be05ba557e309f98e5cfcfa8f664287dd3b538`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.18.0-cp37-abi3-win_amd64.whl:

Publisher: python-publish.yml on shuruheel/mnestic

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mnestic-0.18.0-cp37-abi3-win_amd64.whl
- Subject digest: 9d9e9e85bdb36c23757f7ec1fe56b8ba402df9d8fce3fe576806ada6da4b5f32
- Sigstore transparency entry: 2732550735
- Sigstore integration time: Sep 5, 2026
Source repository:
- Permalink: shuruheel/mnestic@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Branch / Tag: refs/tags/py-v0.18.0
- Owner: https://github.com/shuruheel
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Trigger Event: push

File details

Details for the file mnestic-0.18.0-cp37-abi3-manylinux_2_28_x86_64.whl.

File metadata

Download URL: mnestic-0.18.0-cp37-abi3-manylinux_2_28_x86_64.whl
Upload date: Sep 5, 2026
Size: 15.6 MB
Tags: CPython 3.7+, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mnestic-0.18.0-cp37-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`5ac23fd285f9439db4df0d29b54db8b883ebead0ed1e494bb0bcd161fde74dcc`
MD5	`79ed954f058d9697d163a8808d19b81c`
BLAKE2b-256	`864a28e0134ecadd048cc32fdf53b142b210a8196cc1ab4285d621bf1c708e2c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.18.0-cp37-abi3-manylinux_2_28_x86_64.whl:

Publisher: python-publish.yml on shuruheel/mnestic

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mnestic-0.18.0-cp37-abi3-manylinux_2_28_x86_64.whl
- Subject digest: 5ac23fd285f9439db4df0d29b54db8b883ebead0ed1e494bb0bcd161fde74dcc
- Sigstore transparency entry: 2732550352
- Sigstore integration time: Sep 5, 2026
Source repository:
- Permalink: shuruheel/mnestic@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Branch / Tag: refs/tags/py-v0.18.0
- Owner: https://github.com/shuruheel
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Trigger Event: push

File details

Details for the file mnestic-0.18.0-cp37-abi3-manylinux_2_28_aarch64.whl.

File metadata

Download URL: mnestic-0.18.0-cp37-abi3-manylinux_2_28_aarch64.whl
Upload date: Sep 5, 2026
Size: 15.5 MB
Tags: CPython 3.7+, manylinux: glibc 2.28+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mnestic-0.18.0-cp37-abi3-manylinux_2_28_aarch64.whl
Algorithm	Hash digest
SHA256	`15acf7fe2c9e8768e01d2dea263302551b087d3db7cefda37daa74c6d3bf1e40`
MD5	`1630f750fdafee8243932117dc639d0c`
BLAKE2b-256	`6638d1b7a6ff5c783f6338bf16c8d9f6f8d2f8d2e1db4e306a7b58421379681a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.18.0-cp37-abi3-manylinux_2_28_aarch64.whl:

Publisher: python-publish.yml on shuruheel/mnestic

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mnestic-0.18.0-cp37-abi3-manylinux_2_28_aarch64.whl
- Subject digest: 15acf7fe2c9e8768e01d2dea263302551b087d3db7cefda37daa74c6d3bf1e40
- Sigstore transparency entry: 2732550500
- Sigstore integration time: Sep 5, 2026
Source repository:
- Permalink: shuruheel/mnestic@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Branch / Tag: refs/tags/py-v0.18.0
- Owner: https://github.com/shuruheel
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Trigger Event: push

File details

Details for the file mnestic-0.18.0-cp37-abi3-macosx_11_0_x86_64.whl.

File metadata

Download URL: mnestic-0.18.0-cp37-abi3-macosx_11_0_x86_64.whl
Upload date: Sep 5, 2026
Size: 13.7 MB
Tags: CPython 3.7+, macOS 11.0+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mnestic-0.18.0-cp37-abi3-macosx_11_0_x86_64.whl
Algorithm	Hash digest
SHA256	`76481ccb60c9631fdd8a86261fd36542e884eea9e8bbe1a95cf60d150b128fd9`
MD5	`df6cee21b334876e6650ca9025113c94`
BLAKE2b-256	`ae30341bbd98a65819a7c38eb247c182efb01aa4f034e2001cd47595b7cd5a52`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.18.0-cp37-abi3-macosx_11_0_x86_64.whl:

Publisher: python-publish.yml on shuruheel/mnestic

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mnestic-0.18.0-cp37-abi3-macosx_11_0_x86_64.whl
- Subject digest: 76481ccb60c9631fdd8a86261fd36542e884eea9e8bbe1a95cf60d150b128fd9
- Sigstore transparency entry: 2732550266
- Sigstore integration time: Sep 5, 2026
Source repository:
- Permalink: shuruheel/mnestic@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Branch / Tag: refs/tags/py-v0.18.0
- Owner: https://github.com/shuruheel
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Trigger Event: push

File details

Details for the file mnestic-0.18.0-cp37-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: mnestic-0.18.0-cp37-abi3-macosx_11_0_arm64.whl
Upload date: Sep 5, 2026
Size: 12.4 MB
Tags: CPython 3.7+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mnestic-0.18.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`1c042b400ad3ad464e1c6a0923e4f933b36f59d367dddbb3bc2866d57cbe7abc`
MD5	`205e263296c9a786f3b50622a61985f8`
BLAKE2b-256	`50850bde90110b3d461b0148a9e95ae6d07942629203b323f7399d14764c31bb`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.18.0-cp37-abi3-macosx_11_0_arm64.whl:

Publisher: python-publish.yml on shuruheel/mnestic

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mnestic-0.18.0-cp37-abi3-macosx_11_0_arm64.whl
- Subject digest: 1c042b400ad3ad464e1c6a0923e4f933b36f59d367dddbb3bc2866d57cbe7abc
- Sigstore transparency entry: 2732550605
- Sigstore integration time: Sep 5, 2026
Source repository:
- Permalink: shuruheel/mnestic@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Branch / Tag: refs/tags/py-v0.18.0
- Owner: https://github.com/shuruheel
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@1d13aedc7a309105ae147f2ed1d79cd18a078b00
- Trigger Event: push