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.17.0

0.17.0 adds atomic local Parquet/Arrow copy-in and candidate-scoped full-text retrieval. import_columnar_file accepts an explicit format, projects into an existing non-TxTime relation, and commits every decoded row or none of them:

report = db.import_columnar_file(
    "events",
    "events.parquet",
    format="parquet",
    columns={"event_id": "id"},
    max_rows=1_000_000,
)

The report gives rows_processed, batches_processed, and the HNSW/FTS/LSH indexes that require ::reindex. The method releases the GIL while decoding and committing; published wheels and source distributions both include it.

FTS atoms used through run_script now accept a constant candidates: list of base-relation primary keys. The allowlist is applied before sorting and top-k, while BM25 statistics remain corpus-global, so an eligible document keeps the same score and can surface even when it falls below the unrestricted top-k.

Columnar import requires one process-readable local file and an existing relation. It does not infer schemas, import into TxTime relations, maintain search indexes, or export Arrow. No storage migration is required.

See the fork changelog for the full accounting, and for 0.13.0's upgrade guidance if you are coming from an earlier release (::reindex for HNSW/FTS indexes, pre-1970 timestamps, and the hybrid-leg ranking changes).

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.17.0.tar.gz (776.4 kB view details)

Uploaded Aug 31, 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.17.0-cp37-abi3-win_amd64.whl (12.6 MB view details)

Uploaded Aug 31, 2026 CPython 3.7+Windows x86-64

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

Uploaded Aug 31, 2026 CPython 3.7+manylinux: glibc 2.28+ x86-64

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

Uploaded Aug 31, 2026 CPython 3.7+manylinux: glibc 2.28+ ARM64

mnestic-0.17.0-cp37-abi3-macosx_11_0_x86_64.whl (13.9 MB view details)

Uploaded Aug 31, 2026 CPython 3.7+macOS 11.0+ x86-64

mnestic-0.17.0-cp37-abi3-macosx_11_0_arm64.whl (12.6 MB view details)

Uploaded Aug 31, 2026 CPython 3.7+macOS 11.0+ ARM64

File details

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

File metadata

Download URL: mnestic-0.17.0.tar.gz
Upload date: Aug 31, 2026
Size: 776.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mnestic-0.17.0.tar.gz
Algorithm	Hash digest
SHA256	`1fd287aa4eef801aea8b46830e67245fb06d4b448122f582e5c5143f32c5fa06`
MD5	`3d2a69a20ef511d731236b1b90c51af0`
BLAKE2b-256	`f48fb840273b4fd05cd07a31fe800b4454ac21b884b41db0a68671a8fc14087a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.17.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.17.0.tar.gz
- Subject digest: 1fd287aa4eef801aea8b46830e67245fb06d4b448122f582e5c5143f32c5fa06
- Sigstore transparency entry: 2669442816
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: shuruheel/mnestic@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Branch / Tag: refs/tags/py-v0.17.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@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.17.0-cp37-abi3-win_amd64.whl
Upload date: Aug 31, 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.17.0-cp37-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`f02babdec5c7a5750180bd5ecdcb445a355dc79fe2490fb1c07220a62557dd36`
MD5	`7580c307c4c738fab3b076ff30ca3d7a`
BLAKE2b-256	`561505628233f20bf1a08c93931885a47a3d364224defed6a8ff116eea7d7c02`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.17.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.17.0-cp37-abi3-win_amd64.whl
- Subject digest: f02babdec5c7a5750180bd5ecdcb445a355dc79fe2490fb1c07220a62557dd36
- Sigstore transparency entry: 2669442857
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: shuruheel/mnestic@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Branch / Tag: refs/tags/py-v0.17.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@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.17.0-cp37-abi3-manylinux_2_28_x86_64.whl
Upload date: Aug 31, 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.17.0-cp37-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`6350abadb040a6f36c3da5fcbd85224cf3212ed2baba5b765d3de282a92b2fdd`
MD5	`5a01f206bac49eeff3974b7ab78d5c21`
BLAKE2b-256	`6d87789fbb18ca5695fef4339a0f0c53623bf4e244e15934ed6025dcb5840b89`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.17.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.17.0-cp37-abi3-manylinux_2_28_x86_64.whl
- Subject digest: 6350abadb040a6f36c3da5fcbd85224cf3212ed2baba5b765d3de282a92b2fdd
- Sigstore transparency entry: 2669442839
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: shuruheel/mnestic@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Branch / Tag: refs/tags/py-v0.17.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@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.17.0-cp37-abi3-manylinux_2_28_aarch64.whl
Upload date: Aug 31, 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.17.0-cp37-abi3-manylinux_2_28_aarch64.whl
Algorithm	Hash digest
SHA256	`cfb551dbe39446daa7bbf35f2fbd57a5bdbcead60c9d612fd0ec5e3ed76fefb4`
MD5	`a3fd037d8363ee90d1518bb13a1fb93e`
BLAKE2b-256	`a2ec7491ca21f8b3f64ee2f7dc6a0c56804c389370ea5921461e7e458c43ab9a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.17.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.17.0-cp37-abi3-manylinux_2_28_aarch64.whl
- Subject digest: cfb551dbe39446daa7bbf35f2fbd57a5bdbcead60c9d612fd0ec5e3ed76fefb4
- Sigstore transparency entry: 2669442890
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: shuruheel/mnestic@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Branch / Tag: refs/tags/py-v0.17.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@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.17.0-cp37-abi3-macosx_11_0_x86_64.whl
Upload date: Aug 31, 2026
Size: 13.9 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.17.0-cp37-abi3-macosx_11_0_x86_64.whl
Algorithm	Hash digest
SHA256	`7433cd3e45d3675a7d94530d6f544768b22163e2dc1d84e21af04b2f94ffc335`
MD5	`d7132f3dd919eed36a07e6d32ce4e2eb`
BLAKE2b-256	`26eeb8954358728905aa7a13559d8a5485e570eef34adbe7c31a93efec8141c5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.17.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.17.0-cp37-abi3-macosx_11_0_x86_64.whl
- Subject digest: 7433cd3e45d3675a7d94530d6f544768b22163e2dc1d84e21af04b2f94ffc335
- Sigstore transparency entry: 2669442849
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: shuruheel/mnestic@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Branch / Tag: refs/tags/py-v0.17.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@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.17.0-cp37-abi3-macosx_11_0_arm64.whl
Upload date: Aug 31, 2026
Size: 12.6 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.17.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`9741865f1f92715c9c791e846967dc1be819118bf7be942c259e37a9b78f6c9a`
MD5	`520ac9c6aa4e0ff718f745b003134cc0`
BLAKE2b-256	`1d6a5671594b4b19141fe84ca642e0c0482bd3db391235b7b2a795e53e3c4830`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.17.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.17.0-cp37-abi3-macosx_11_0_arm64.whl
- Subject digest: 9741865f1f92715c9c791e846967dc1be819118bf7be942c259e37a9b78f6c9a
- Sigstore transparency entry: 2669442870
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: shuruheel/mnestic@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Branch / Tag: refs/tags/py-v0.17.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@786c3a8f7bb2b9a646be08aa76422700a2b550b7
- Trigger Event: push