mnestic 0.8.3__tar.gz

mnestic-0.8.3/Cargo.toml

@@ -0,0 +1,26 @@
+[workspace]
+resolver = "2"
+members = [
+    "cozo-core",
+    "cozorocks",
+    "cozo-bin",
+    "cozo-core-examples",
+]
+# Language bindings are deferred in the mnestic fork — the fork targets a Rust
+# agentic-memory substrate (consumed by mindgraph-rs). The binding crates are
+# kept in-tree but excluded from the workspace build/maintenance for now.
+exclude = [
+    "cozo-lib-c",
+    "cozo-lib-java",
+    "cozo-lib-wasm",
+    "cozo-lib-swift",
+    "cozo-lib-python",
+    "cozo-lib-nodejs",
+]
+
+[profile.bench]
+lto = true
+debug = true
+
+[profile.dev.package."mnestic-rocks"]
+opt-level = 3

mnestic-0.8.3/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: mnestic
+Version: 0.8.3
+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), ...
+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}
+```
+
+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.
+

mnestic-0.8.3/README.md

@@ -0,0 +1,44 @@
+# 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), ...
+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}
+```
+
+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.

mnestic-0.8.3/cozo-core/Cargo.toml

@@ -0,0 +1,167 @@
+[package]
+name = "mnestic"
+version = "0.8.3"
+edition = "2021"
+description = "A transactional relational-graph-vector database using Datalog — a maintained fork of CozoDB, tuned as a substrate for agentic memory"
+authors = ["Shan Rizvi", "Ziyang Hu (original CozoDB author)"]
+license = "MPL-2.0"
+repository = "https://github.com/shuruheel/mnestic"
+readme = "README-mnestic.md"
+keywords = ["database", "datalog", "graph", "vector", "embedded"]
+categories = ["database", "database-implementations"]
+exclude = [
+    "tests/*",
+]
+
+# The published package is `mnestic`, but the importable Rust crate name stays
+# `cozo` so that downstream `use cozo::...` (including this crate's own tests,
+# benches, and doctests) continues to work unchanged. See FORK.md.
+[lib]
+name = "cozo"
+
+[features]
+#! # Features
+
+default = ["compact"]
+## Enables the `minimal`, `requests` and `graph-algo` features.
+compact = ["minimal", "requests", "graph-algo"]
+## Enables the `minimal`, `requests` and `graph-algo` features in single threaded mode.
+compact-single-threaded = ["minimal", "requests", "graph-algo"]
+## Enables the `storage-sqlite` feature.
+minimal = ["storage-sqlite", "storage-sqlite-src"]
+## Enables the [Sqlite](https://www.sqlite.org/index.html) backend,
+## also allows backup and restore with Sqlite data files.
+## Sqlite is easy to compile, has very low resource requirements and reasonable performance,
+## but does not support much concurrency.
+storage-sqlite = ["dep:sqlite"]
+storage-sqlite-src = ["dep:sqlite3-src", "sqlite3-src/bundled"]
+## Enables the [RocksDB](http://rocksdb.org/) backend.
+## RocksDB is hard to compile on some platforms, uses more resources than SQLite,
+## but is very performant and supports an extremely high level of concurrency.
+## You can also [fine-tune](https://github.com/cozodb/cozo/blob/main/TUNING_ROCKSDB.md) RocksDB options.
+storage-rocksdb = ["dep:cozorocks"]
+storage-new-rocksdb = ["dep:rocksdb"]
+## Enables the graph algorithms.
+graph-algo = ["graph", "rayon"]
+## Allows the utilities to make web requests to fetch data.
+requests = ["dep:minreq"]
+## Uses jemalloc as the global allocator, can make a difference in performance.
+jemalloc = ["dep:tikv-jemallocator-global", "cozorocks?/jemalloc"]
+## Enables io-uring option for the RocksDB storage
+io-uring = ["cozorocks?/io-uring"]
+## Polyfills for the WASM target
+wasm = ["uuid/js", "dep:js-sys"]
+
+#! The following features are highly experimental:
+
+## Enables the [Sled](https://github.com/spacejam/sled) backend.
+## Sled is slower than Sqlite for the usual workload of Cozo, can use quite a lot of disk space,
+## and may not be stable enough. In general you should use RocksDB instead.
+## The Sled engine does not support time travel.
+storage-sled = ["dep:sled"]
+## Enables the [TiKV](https://tikv.org/) client backend.
+## The only reason that you may want to use this is that your data does not fit in a single machine.
+## This engine is orders of magnitude slower than every other engine for graph traversals, due to the
+## significant network overhead. Simple point-lookup queries are fine, though.
+## The TiKV engine does not support time travel.
+storage-tikv = ["dep:tikv-client", "dep:tokio"]
+
+#! # Recommendation for features to enable
+#!
+#! Generally you will want the `storage-sqlite` and `graph-algo` features enabled,
+#! unless your environment makes compiling them difficult. The backup/restore functionalities
+#! are only available if `storage-sqlite` is on. Without `graph-algo` you cannot use any graph algorithms
+#! (utilities are still available),
+#! which could be OK if you only want to deal with pure Datalog.
+#!
+#! The `requests` feature allows the database to make outgoing HTTP requests to fetch data
+#! into queries -- only enable it if you need it.
+#!
+#! The `wasm` feature simply patches some functions so that they can compile on WASM platform,
+#! which lacks some std implementations at the moment. (On WASM you must also enable `nothread`).
+#! This feature will not work on any other platform.
+#!
+#! The `jemalloc` feature only makes sense for desktop and servers. It could improve performance,
+#! sometimes substantially, but you need to benchmark for your use case. It also tends to break
+#! builds on untested platforms. None of our prebuilt binaries have it enabled.
+#!
+#! Enable `storage-rocksdb` if you expect high concurrency or want better performance than SQLite,
+#! but note that RocksDB is much more resource-hungry and takes long to compile.
+#!
+#! The other storage options are just for experimentation. We do not recommend using them.
+
+[dependencies]
+casey = "0.4.0"
+either = "1.11.0"
+rand = "0.8.5"
+miette = { version = "5.10.0", features = ["fancy"] }
+lazy_static = "1.4.0"
+log = "0.4.21"
+smallvec = { version = "1.13.2", features = ["serde", "write", "union", "const_generics", "const_new"] }
+smartstring = { version = "1.0.1", features = ["serde"] }
+serde_json = "1.0.116"
+serde = { version = "1.0.199" }
+serde_derive = "1.0.199"
+serde_bytes = "0.11.14"
+rmp = "0.8.14"
+rmp-serde = "1.2.0"
+rmpv = "1.0.2"
+base64 = "0.22.0"
+chrono = "0.4.38"
+chrono-tz = "0.9.0"
+priority-queue = "1.4.0"
+ordered-float = "4.2.0"
+byteorder = "1.5.0"
+num-traits = "0.2.18"
+itertools = "0.12.1"
+regex = "1.10.4"
+pest = "2.7.9"
+pest_derive = "2.7.9"
+approx = "0.5.1"
+unicode-normalization = "0.1.23"
+thiserror = "1.0.59"
+uuid = { version = "1.8.0", features = ["v1", "v4", "serde"] }
+csv = "1.3.0"
+document-features = "0.2.8"
+rayon = { version = "1.10.0", optional = true }
+minreq = { version = "2.11.2", features = ["https-rustls"], optional = true }
+tikv-jemallocator-global = { version = "0.5.0", optional = true }
+cozorocks = { package = "mnestic-rocks", path = "../cozorocks", version = "0.1.8", optional = true }
+rocksdb = { version = "0.22.0", optional = true }
+sled = { version = "0.34.7", optional = true }
+tikv-client = { version = "0.3.0", optional = true }
+tokio = { version = "1.37.0", optional = true }
+sqlite = { version = "0.36.0", optional = true }
+sqlite3-src = { version = "0.6.1", optional = true }
+js-sys = { version = "0.3.60", optional = true }
+graph = { version = "0.3.1", optional = true }
+crossbeam = "0.8.4"
+ndarray = { version = "0.15.6", features = ["serde"] }
+sha2 = "0.10.8"
+rustc-hash = "1.1.0"
+twox-hash = "1.6.3"
+quadrature = "0.1.2"
+# For the FTS feature
+jieba-rs = "0.7.0"
+aho-corasick = "1.1.3"
+rust-stemmers = "1.2.0"
+fast2s = "0.3.1"
+swapvec = "0.3.0"
+
+[dev-dependencies]
+tempfile = "3.14.0"
+# Test-only: only `runtime/tests.rs` (cfg(test)) initializes a logger. Moved out
+# of [dependencies] so it doesn't bloat downstream builds (upstream cozo #287).
+env_logger = "0.11.3"
+# CI/stable-runnable perf harness for fork work (the upstream pokec/wiki/
+# time_travel benches use the nightly `#![feature(test)]` bencher + external data).
+criterion = { version = "0.5", features = ["html_reports"] }
+
+# mnestic fork perf baselines (stable, self-contained synthetic data).
+[[bench]]
+name = "point_lookup"
+harness = false
+
+[[bench]]
+name = "read_path"
+harness = false

mnestic-0.8.3/cozo-core/README-mnestic.md

@@ -0,0 +1,110 @@
+# mnestic
+
+**mnestic** is an independently maintained fork of
+[CozoDB](https://github.com/cozodb/cozo) — a transactional,
+relational-graph-vector database that uses Datalog for queries ("the
+hippocampus for AI"). The fork continues the project as a substrate for
+**agentic memory**, with performance, correctness, and operational work on top
+of upstream `481af05` (the last upstream commit, 2024-12-04).
+
+> 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
+> [`FORK.md`](https://github.com/shuruheel/mnestic/blob/main/FORK.md) for
+> provenance and licensing, and
+> [`CHANGELOG-FORK.md`](https://github.com/shuruheel/mnestic/blob/main/CHANGELOG-FORK.md)
+> for what diverges from upstream.
+
+## What mnestic adds over CozoDB
+
+Highlights (full detail in
+[`CHANGELOG-FORK.md`](https://github.com/shuruheel/mnestic/blob/main/CHANGELOG-FORK.md)):
+
+**0.8.3**
+
+- **Native 3-way fused recall** — `hybrid_search` now fuses a graph-proximity leg
+  *in-engine* alongside vector (HNSW) and full-text (FTS). A typed `GraphLeg`
+  generates a recursive bounded shortest-path rule (k-hop, `min(dist)` scoring) and
+  folds it into the same RRF, so one call returns the vector+FTS+graph ranking — a
+  capability no other embedded engine here offers. Measured **41.55 ms p50**, ~4×
+  faster than the hand-decomposed three-query path.
+- **BM25-correct FTS, with O(1) `avgdl`** — the default `::fts` scorer is now Okapi
+  **`bm25`** (term-frequency saturation `k1` + document-length normalization `b`,
+  both tunable; `OR` sums per-term contributions). Average document length is an O(1)
+  read of a durable per-index counter rather than a per-query index scan. Measured:
+  fused recall **0.75 → 0.954** (parity with DuckDB / SQLite) at no net latency cost
+  (decomposed p50 927 → 175 ms, cold p99 2,900 → 258 ms). **Heads-up:** this changes
+  the default FTS score kind (a behaviour change); `tf`/`tf_idf` stay selectable for
+  byte-identical upstream scoring.
+
+**0.8.2**
+
+- **Non-blocking HNSW index builds** — `::hnsw create` no longer holds the base
+  relation's write lock during graph construction, so concurrent reads are no
+  longer stalled for the whole build (previously 10–20+ min in production). Built
+  off-lock under a snapshot and bulk-published via `SstFileWriter`/
+  `IngestExternalFile`; concurrent mutations reconciled under a brief final lock.
+  Measured: 90,507 reads completed (slowest 0.8 ms) during a ~5.6 s 40k-vector
+  build. RocksDB only.
+
+**0.8.1**
+
+- **One-call hybrid retrieval** — `DbInstance::hybrid_search` runs HNSW + FTS
+  (+ optional graph traversal), fuses with RRF, and optionally diversifies with
+  MMR in a single typed call (was ~7 hand-written Datalog rules).
+- **HNSW index build ~3× faster** — the build no longer round-trips the whole
+  graph through the transaction's write-batch overlay (20k × 128: 135s → 43.6s,
+  measured release). Built graph is byte-identical.
+- **`mnestic-rocks`** — the C++/RocksDB bridge is now a maintained fork
+  (importable name stays `cozorocks`), unblocking future bridge-level work.
+
+**0.8.0 — fixes**
+
+- **Equality pushdown** — `*rel[k, ..], k == <value>` now compiles to a keyed
+  `stored_prefix_join` instead of a full scan (**~28–29× faster** single-row
+  primary-key lookups, measured at 5k rows). Numeric equalities keep cross-type
+  `op_eq` semantics.
+- **Parser fix** — identifiers that start with a keyword literal
+  (`nullable_column`, `trueValue`, `falsey`) now parse correctly (upstream #281).
+- **Unreleased upstream fixes for free** — the fork point is 30 commits ahead of
+  the published 0.7.6, including the `stored_prefix_join` correctness fix.
+- `env_logger` moved to a dev-dependency for a slimmer dependency graph
+  (upstream #287).
+
+**0.8.0 — new: hybrid retrieval for agentic memory** (Datalog-composable fixed rules)
+
+- `ReciprocalRankFusion` (alias `RRF`) — fuse vector (HNSW) + full-text (FTS) +
+  graph-traversal result lists into one ranking.
+- `MaximalMarginalRelevance` (alias `MMR`) — diversity-aware reranking that avoids
+  near-duplicate recalls.
+- `rand_ulid()` / `ulid_timestamp()` — lexicographically-sortable identifiers for
+  time-ordered scans (upstream #296).
+
+## Importable name
+
+The published crate is `mnestic`, but the importable Rust crate name is `cozo`,
+so existing CozoDB code works unchanged:
+
+```toml
+[dependencies]
+mnestic = "0.8.3"
+```
+
+```rust
+use cozo::{DbInstance, ScriptMutability};
+```
+
+The query language (CozoScript / Datalog) and engine semantics are unchanged
+unless noted in the fork changelog.
+
+## Features
+
+Default is `compact` (SQLite backend). RocksDB, vector (HNSW), full-text search,
+and graph-algorithm features match upstream Cozo 0.7.x. See the crate docs and
+the [upstream CozoDB documentation](https://docs.cozodb.org/) for the query
+language and feature flags.
+
+## License
+
+Mozilla Public License 2.0. Original work © 2022 The Cozo Project Authors;
+fork modifications © 2026 Shan Rizvi.

mnestic-0.8.3/cozo-core/README-zh.md

@@ -0,0 +1,5 @@
+# Cozo-core
+
+[![Crates.io](https://img.shields.io/crates/v/cozo)](https://crates.io/crates/cozo)
+
+Cozo 数据库核心部分的实现。

mnestic-0.8.3/cozo-core/README.md

@@ -0,0 +1,5 @@
+# Cozo-core
+
+[![Crates.io](https://img.shields.io/crates/v/cozo)](https://crates.io/crates/cozo)
+
+This crate contains the implementation proper of CozoDB.

mnestic-0.8.3/cozo-core/benches/point_lookup.rs

@@ -0,0 +1,91 @@
+/*
+ * Copyright 2026, Shan Rizvi (mnestic fork).
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+ * If a copy of the MPL was not distributed with this file,
+ * You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+//! Baseline for fork #1 (equality-pushdown). Times a single-row primary-key
+//! lookup written three ways against an N-row stored relation on the SQLite
+//! backend:
+//!   - `eq_postfilter_positional`: `*rel[uid, val], uid == $u`   (the slow shape)
+//!   - `eq_postfilter_brace`:      `*rel{uid, val}, uid == $u`   (the slow shape)
+//!   - `binding_first`:            `uid = $u, *rel{uid, val}`    (the fast shape)
+//!
+//! Before the fix, the post-filter shapes do an O(N) `load_stored` scan; after,
+//! all three compile to an O(log N) `stored_prefix_join`. Run:
+//!   cargo bench -p mnestic --bench point_lookup
+
+use std::collections::BTreeMap;
+
+use cozo::{DataValue, DbInstance, ScriptMutability};
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
+
+const N: usize = 5000;
+
+fn make_db() -> (tempfile::TempDir, DbInstance) {
+    let dir = tempfile::tempdir().unwrap();
+    let db = DbInstance::new(
+        "sqlite",
+        dir.path().join("point_lookup.db").to_str().unwrap(),
+        Default::default(),
+    )
+    .unwrap();
+    db.run_script(
+        ":create pk_test { uid: String => val: String }",
+        BTreeMap::new(),
+        ScriptMutability::Mutable,
+    )
+    .unwrap();
+
+    // Insert N rows in chunks via a constant relation.
+    let mut i = 0;
+    while i < N {
+        let end = (i + 500).min(N);
+        let rows: Vec<String> = (i..end)
+            .map(|k| format!(r#"["k{k}","v{k}"]"#))
+            .collect();
+        let script = format!(
+            "?[uid, val] <- [{}] :put pk_test {{ uid => val }}",
+            rows.join(",")
+        );
+        db.run_script(&script, BTreeMap::new(), ScriptMutability::Mutable)
+            .unwrap();
+        i = end;
+    }
+    (dir, db)
+}
+
+fn bench_point_lookup(c: &mut Criterion) {
+    let (_dir, db) = make_db();
+    // Look up a key in the middle of the keyspace.
+    let mut params = BTreeMap::new();
+    params.insert("u".to_string(), DataValue::Str(format!("k{}", N / 2).into()));
+
+    let mut group = c.benchmark_group("point_lookup");
+    for (name, query) in [
+        (
+            "eq_postfilter_positional",
+            "?[uid, val] := *pk_test[uid, val], uid == $u",
+        ),
+        (
+            "eq_postfilter_brace",
+            "?[uid, val] := *pk_test{uid, val}, uid == $u",
+        ),
+        ("binding_first", "?[uid, val] := uid = $u, *pk_test{uid, val}"),
+    ] {
+        group.bench_with_input(BenchmarkId::from_parameter(name), &query, |b, q| {
+            b.iter(|| {
+                let res = db
+                    .run_script(q, params.clone(), ScriptMutability::Immutable)
+                    .unwrap();
+                assert_eq!(res.rows.len(), 1);
+            })
+        });
+    }
+    group.finish();
+}
+
+criterion_group!(benches, bench_point_lookup);
+criterion_main!(benches);