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.

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

Python callers can now define and invoke persistent named read queries through the existing run_script API:

db.run_script("""
::query create recent_items ($since: Int) {
    ?[uid, created_at] := *item{uid, created_at}, created_at >= $since
}
""", {}, False)

rows = db.run_script(
    "::query run recent_items",
    {"since": 1_700_000_000},
    True,
)["rows"]

Stored queries have introspectable typed/defaulted parameters, compose as ordinary rule atoms, survive reopen and export/import, and always evaluate current transaction data. Bodies are read-only in v1; this is not a plan cache or a materialized-result feature. 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.16.0.tar.gz (761.1 kB view details)

Uploaded Aug 18, 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.16.0-cp37-abi3-win_amd64.whl (11.0 MB view details)

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

mnestic-0.16.0-cp37-abi3-manylinux_2_28_x86_64.whl (13.7 MB view details)

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

mnestic-0.16.0-cp37-abi3-manylinux_2_28_aarch64.whl (13.5 MB view details)

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

mnestic-0.16.0-cp37-abi3-macosx_11_0_x86_64.whl (12.1 MB view details)

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

mnestic-0.16.0-cp37-abi3-macosx_11_0_arm64.whl (10.8 MB view details)

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

File details

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

File metadata

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

File hashes

Hashes for mnestic-0.16.0.tar.gz
Algorithm	Hash digest
SHA256	`814ff29e8c8fcad4d800ce60ac047e904131fa0dba2fea9d0ea06f78b93023cc`
MD5	`4df30e1c565fd525c4ec7cde2c9ca817`
BLAKE2b-256	`6503d2d8cb9a8872f111c0ada1d0ea5a565f4a12e2b964a7c414e1a140b952db`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.16.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.16.0.tar.gz
- Subject digest: 814ff29e8c8fcad4d800ce60ac047e904131fa0dba2fea9d0ea06f78b93023cc
- Sigstore transparency entry: 2509383094
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: shuruheel/mnestic@99212e257ef84cd518aca117f9225b85bee094d0
- Branch / Tag: refs/tags/py-v0.16.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@99212e257ef84cd518aca117f9225b85bee094d0
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.16.0-cp37-abi3-win_amd64.whl
Upload date: Aug 18, 2026
Size: 11.0 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.16.0-cp37-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`e5e03903fbacb15e0e71e4fd9a3ab2967a22e97a6b46775f2f6a6776c3365dfc`
MD5	`f589d5d2624b6510856e6b7ebc9dcb1b`
BLAKE2b-256	`825f90062ead562dbd06b80c89faff4bf18c854eb2de6c3d023399706bda87b4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.16.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.16.0-cp37-abi3-win_amd64.whl
- Subject digest: e5e03903fbacb15e0e71e4fd9a3ab2967a22e97a6b46775f2f6a6776c3365dfc
- Sigstore transparency entry: 2509386068
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: shuruheel/mnestic@99212e257ef84cd518aca117f9225b85bee094d0
- Branch / Tag: refs/tags/py-v0.16.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@99212e257ef84cd518aca117f9225b85bee094d0
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.16.0-cp37-abi3-manylinux_2_28_x86_64.whl
Upload date: Aug 18, 2026
Size: 13.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.16.0-cp37-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`0fa6536347806d8c8a8031031eb1bac3feb0edd812d2341835121f5d015811a7`
MD5	`5e03038b2008b99d68c9e55558fdd721`
BLAKE2b-256	`9948ae2c8f818447c86334d79f50fcd67712057823e7707508cdd40db66cb8ec`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.16.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.16.0-cp37-abi3-manylinux_2_28_x86_64.whl
- Subject digest: 0fa6536347806d8c8a8031031eb1bac3feb0edd812d2341835121f5d015811a7
- Sigstore transparency entry: 2509384336
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: shuruheel/mnestic@99212e257ef84cd518aca117f9225b85bee094d0
- Branch / Tag: refs/tags/py-v0.16.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@99212e257ef84cd518aca117f9225b85bee094d0
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.16.0-cp37-abi3-manylinux_2_28_aarch64.whl
Upload date: Aug 18, 2026
Size: 13.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.16.0-cp37-abi3-manylinux_2_28_aarch64.whl
Algorithm	Hash digest
SHA256	`92fb899f6ba8b8e9dfb6d538dbad48898dc941f562872728fb3cd0d09110231c`
MD5	`03e6495270662dcdf53fae4f13224b52`
BLAKE2b-256	`5bf1b7b7b9be6ae1319393a5cd38bc73cff91f70cc8398ee293a0192cb0e0312`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.16.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.16.0-cp37-abi3-manylinux_2_28_aarch64.whl
- Subject digest: 92fb899f6ba8b8e9dfb6d538dbad48898dc941f562872728fb3cd0d09110231c
- Sigstore transparency entry: 2509387863
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: shuruheel/mnestic@99212e257ef84cd518aca117f9225b85bee094d0
- Branch / Tag: refs/tags/py-v0.16.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@99212e257ef84cd518aca117f9225b85bee094d0
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.16.0-cp37-abi3-macosx_11_0_x86_64.whl
Upload date: Aug 18, 2026
Size: 12.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.16.0-cp37-abi3-macosx_11_0_x86_64.whl
Algorithm	Hash digest
SHA256	`1fd7e59d74271152b147d0e89b4e706333273941d13d1b4d1d1a93f4737a4bf0`
MD5	`540e045993c3c6076794aaea44a7e691`
BLAKE2b-256	`5553fe684d0e4c9c57d1782c9a01cc2f3dbd2710c749fb6d439ce2d0055f1fe4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.16.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.16.0-cp37-abi3-macosx_11_0_x86_64.whl
- Subject digest: 1fd7e59d74271152b147d0e89b4e706333273941d13d1b4d1d1a93f4737a4bf0
- Sigstore transparency entry: 2509387123
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: shuruheel/mnestic@99212e257ef84cd518aca117f9225b85bee094d0
- Branch / Tag: refs/tags/py-v0.16.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@99212e257ef84cd518aca117f9225b85bee094d0
- Trigger Event: push

File details

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

File metadata

Download URL: mnestic-0.16.0-cp37-abi3-macosx_11_0_arm64.whl
Upload date: Aug 18, 2026
Size: 10.8 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.16.0-cp37-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`693711afc455a60dfb41afa426d991c222b2cfe121f869d63651143169234ccd`
MD5	`23212372710aaad5fbbf54b8abc24f64`
BLAKE2b-256	`ec7d5c7292125ad03bb8cfb32b3386420a5aa04ab156b03ad98bed1adde85872`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mnestic-0.16.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.16.0-cp37-abi3-macosx_11_0_arm64.whl
- Subject digest: 693711afc455a60dfb41afa426d991c222b2cfe121f869d63651143169234ccd
- Sigstore transparency entry: 2509388169
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: shuruheel/mnestic@99212e257ef84cd518aca117f9225b85bee094d0
- Branch / Tag: refs/tags/py-v0.16.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@99212e257ef84cd518aca117f9225b85bee094d0
- Trigger Event: push