Metadata-Version: 2.4
Name: mnestic
Version: 0.13.1
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Summary: Embedded graph + vector + full-text database with Datalog — a maintained fork of CozoDB, tuned as a substrate for agentic memory.
Keywords: database,graph,vector,datalog,embeddings,rag,agentic-memory,cozodb
Home-Page: https://github.com/shuruheel/mnestic
Author: Shan Rizvi
License: MPL-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/shuruheel/mnestic
Project-URL: Repository, https://github.com/shuruheel/mnestic

# mnestic (Python)

Embedded **graph + vector + full-text** database with **Datalog** queries — a
maintained fork of [CozoDB](https://github.com/cozodb/cozo), 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](https://github.com/shuruheel/mnestic) for provenance and
> licensing.

```bash
pip install mnestic
```

```python
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.13.1

A patch release. The Python-facing highlights:

- **The factorized `count()` rewrite is ON by default.** Through 0.13.0 you had
  to opt in with `db.set_query_factorization(True)`; the nightly soak that
  gated the flip has run green, so an eligible `count()`-over-join — including
  the inequality form handled by inclusion–exclusion — is now counted without
  materializing the join (measured on LSQB sf0.1: q1 72.4 s → 1.05 s, q6
  42.1 s → 0.31 s, both returning LDBC's published count). Answers are unchanged;
  the rewrite fires only on a provably exact decomposition and leaves every
  query it declines byte-identical. Opt back out with
  `db.set_query_factorization(False)`, and read the setting with
  `db.query_factorization()`.

- **Parse errors name the expected tokens again.** 0.13.0 shipped the `help:`
  line listing the literal tokens that would have been accepted, but pest 2.8
  made the underlying tracking opt-in, so wheels built against it silently lost
  both the token list and the corrected caret position. Restored, and the
  tracking is now enabled only around a re-parse of a script that already
  failed — successful parses pay nothing for it.

See the [fork changelog](https://github.com/shuruheel/mnestic/blob/main/CHANGELOG-FORK.md)
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](https://docs.cozodb.org/) and the
[fork changelog](https://github.com/shuruheel/mnestic/blob/main/CHANGELOG-FORK.md).

## License

Mozilla Public License 2.0. Original work © 2022 The Cozo Project Authors; fork
modifications © 2026 Shan Rizvi.

