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 stays SQLite/compact-only, so the persistent engine is wheel-only.

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.

New in 0.14.0

The Python-facing highlights of this security-first minor release:

Safer defaults. The wheel no longer registers CozoScript's file/network CsvReader and JsonReader utilities. Stored-relation ACLs now cover indexes, negation, fixed rules, exports, history, and cached graph projections; malformed vector payloads fail before unsafe decoding.
Exact-phrase FTS and matched context. Quoted multi-word queries require adjacency and order. FTS atoms can bind the matching byte offsets with bind_spans, and snippet(text, spans, window) formats a window without re-tokenizing the document.
Durability is explicit. db.set_durable_writes(True) requests fsync-on-commit and returns whether the selected backend honors the knob. RocksDB does; SQLite is already durable under its default synchronous=FULL policy and reports False.
Warnings are queryable. ::warnings returns stable warning codes with a message and actionable hint; ::warnings clear empties the per-database buffer.
Hardened framework adapters. langchain-mnestic 0.2.1 and llama-index-vector-stores-mnestic 0.2.1 validate all identifiers and numeric HNSW settings before constructing CozoScript.

Migration highlights: indirect reads of Hidden relations now fail, and quoted multi-word FTS queries now mean exact phrases. Drop the quotes to retain the previous AND-of-terms behavior.

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

Uploaded Aug 8, 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.14.0-cp37-abi3-win_amd64.whl (10.1 MB view details)

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

mnestic-0.14.0-cp37-abi3-manylinux_2_28_x86_64.whl (12.7 MB view details)

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

mnestic-0.14.0-cp37-abi3-manylinux_2_28_aarch64.whl (12.4 MB view details)

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

mnestic-0.14.0-cp37-abi3-macosx_11_0_x86_64.whl (11.1 MB view details)

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

mnestic-0.14.0-cp37-abi3-macosx_11_0_arm64.whl (9.9 MB view details)

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

File details

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

File metadata

Download URL: mnestic-0.14.0.tar.gz
Upload date: Aug 8, 2026
Size: 725.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.14.0.tar.gz
Algorithm	Hash digest
SHA256	`70ccbc609f26f00cc398943f15cbc2350010b6bd659d2781faac78f4ed771541`
MD5	`425395331846cdbbe6effe1def1ed119`
BLAKE2b-256	`97fe80399d9c5bce4436d5de99b16c1bf1b77ce5e282282ec754ab79f30cba54`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.14.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.14.0.tar.gz
- Subject digest: 70ccbc609f26f00cc398943f15cbc2350010b6bd659d2781faac78f4ed771541
- Sigstore transparency entry: 2387284022
- Sigstore integration time: Aug 8, 2026
Source repository:
- Permalink: shuruheel/mnestic@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Branch / Tag: refs/tags/py-v0.14.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@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.14.0-cp37-abi3-win_amd64.whl
Upload date: Aug 8, 2026
Size: 10.1 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.14.0-cp37-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`667b54e91b4706e9af5f1a92b7fd320e24986d54e32be42307e71921346f81b2`
MD5	`a7627da676a2e0f42d081b488ca2eaa7`
BLAKE2b-256	`9738c4ece52a69aebc3ce4809a76bb2f84837ca16512f79a4c8bd9e728c0888b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.14.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.14.0-cp37-abi3-win_amd64.whl
- Subject digest: 667b54e91b4706e9af5f1a92b7fd320e24986d54e32be42307e71921346f81b2
- Sigstore transparency entry: 2387284678
- Sigstore integration time: Aug 8, 2026
Source repository:
- Permalink: shuruheel/mnestic@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Branch / Tag: refs/tags/py-v0.14.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@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.14.0-cp37-abi3-manylinux_2_28_x86_64.whl
Upload date: Aug 8, 2026
Size: 12.7 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.14.0-cp37-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`f91ff635601f9618250f4ec76432f684af28261750169a548bb687064be74b67`
MD5	`e3fc0edee2327a2b31bc6701b4c35770`
BLAKE2b-256	`1d063d6d102ce56fc5459b011015e88f62fb6c701e01576c83e62ca2a5c69aa7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.14.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.14.0-cp37-abi3-manylinux_2_28_x86_64.whl
- Subject digest: f91ff635601f9618250f4ec76432f684af28261750169a548bb687064be74b67
- Sigstore transparency entry: 2387284270
- Sigstore integration time: Aug 8, 2026
Source repository:
- Permalink: shuruheel/mnestic@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Branch / Tag: refs/tags/py-v0.14.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@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.14.0-cp37-abi3-manylinux_2_28_aarch64.whl
Upload date: Aug 8, 2026
Size: 12.4 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.14.0-cp37-abi3-manylinux_2_28_aarch64.whl
Algorithm	Hash digest
SHA256	`082a87499f00e01c5cb44b413e0894f0473cb8395185b7a3fe8b4a4234bf6e43`
MD5	`697b62526b225a39ba56389650a376b4`
BLAKE2b-256	`92bba2b483014d60f0f81da88bc304e7cfd36138f51183b92de85076b26048e4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.14.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.14.0-cp37-abi3-manylinux_2_28_aarch64.whl
- Subject digest: 082a87499f00e01c5cb44b413e0894f0473cb8395185b7a3fe8b4a4234bf6e43
- Sigstore transparency entry: 2387285081
- Sigstore integration time: Aug 8, 2026
Source repository:
- Permalink: shuruheel/mnestic@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Branch / Tag: refs/tags/py-v0.14.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@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.14.0-cp37-abi3-macosx_11_0_x86_64.whl
Upload date: Aug 8, 2026
Size: 11.1 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.14.0-cp37-abi3-macosx_11_0_x86_64.whl
Algorithm	Hash digest
SHA256	`816039537e5d7f2a89a0f6f5ab446b7b2486d86fd974bc31c5f05dfcd8e69573`
MD5	`28485907c5cc6fc0286cc050fc59b523`
BLAKE2b-256	`83b6295ad10c777cbe60f7902dd76d334bef0812c370e87a123b4659c0a926e7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.14.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.14.0-cp37-abi3-macosx_11_0_x86_64.whl
- Subject digest: 816039537e5d7f2a89a0f6f5ab446b7b2486d86fd974bc31c5f05dfcd8e69573
- Sigstore transparency entry: 2387284522
- Sigstore integration time: Aug 8, 2026
Source repository:
- Permalink: shuruheel/mnestic@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Branch / Tag: refs/tags/py-v0.14.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@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.14.0-cp37-abi3-macosx_11_0_arm64.whl
Upload date: Aug 8, 2026
Size: 9.9 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.14.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`cf773b8b904277ec68de157b86b38cef415470b37570dd725c1bfbe55fa3bd0c`
MD5	`f4066a054b2081a4ed0be8203fe0b2bc`
BLAKE2b-256	`84aaf14c201b17310f9fd795d9fb23c6606ab9edd9573e40bfb4b5c50b1c7985`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.14.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.14.0-cp37-abi3-macosx_11_0_arm64.whl
- Subject digest: cf773b8b904277ec68de157b86b38cef415470b37570dd725c1bfbe55fa3bd0c
- Sigstore transparency entry: 2387284873
- Sigstore integration time: Aug 8, 2026
Source repository:
- Permalink: shuruheel/mnestic@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Branch / Tag: refs/tags/py-v0.14.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@5ef1aa44c99b34aef31a159a907b7b53d2c81c2a
- Trigger Event: push