mnem_core/
lib.rs

1//! # mnem-core
2//!
3//! The core library for [mnem] - a content-addressed, versioned substrate for
4//! AI agent memory.
5//!
6//! This crate contains the format types, canonical encoding, content hashing,
7//! Prolly-tree algorithms, operation-log machinery, and repository API.
8//!
9//! ## Scope
10//!
11//! `mnem-core` is deliberately factored to be embeddable in every runtime.
12//! It has:
13//!
14//! - No terminal I/O (`println!`, `eprintln!` are forbidden inside this crate)
15//! - No config-file loading (callers supply config; we consume it)
16//! - No direct filesystem access - storage is behind the [`Blockstore`][store::Blockstore] trait
17//!   (implemented in `mnem-backend-redb` or callers' own backends)
18//! - No `tokio` runtime binding (sync API; async wrappers live in callers)
19//!
20//! These constraints are what make the same source compile to native binaries,
21//! WASM, and FFI-consumed libraries in Python / Node / Go.
22//!
23//! ## Modules
24//!
25//! - [`id`] - identity primitives: `Multihash`, [`Cid`][id::Cid], stable
26//!   [`NodeId`][id::NodeId] / [`EdgeId`][id::EdgeId] /
27//!   [`ChangeId`][id::ChangeId] / [`OperationId`][id::OperationId], and
28//!   phantom-typed [`Link<T>`][id::Link].
29//! - [`codec`] - canonical DAG-CBOR encode/decode and DAG-JSON debug export.
30//! - [`objects`] - [`Node`], [`Edge`], [`Commit`], [`Operation`], [`View`],
31//!   [`IndexSet`] types. Prolly tree chunks live under [`prolly::TreeChunk`].
32//! - [`prolly`] - Prolly tree algorithms (chunker, builder, lookup, cursor,
33//!   diff, merge).
34//! - [`store`] - [`Blockstore`][store::Blockstore] and
35//!   [`OpHeadsStore`][store::OpHeadsStore] traits, plus in-memory
36//!   reference implementations.
37//! - [`repo`] - [`ReadonlyRepo`], [`Transaction`] facade.
38//! - [`index`] - secondary indexes ([`Query`],
39//!   [`BruteForceVectorIndex`]).
40//! - [`retrieve`] - agent-facing [`Retriever`] that composes filters,
41//!   vector and sparse ranking, and token-budget packing.
42//! - [`sign`] - Ed25519 signing and revocation-list verification.
43//!
44//! ## Crate-level invariants
45//!
46//! - `#![forbid(unsafe_code)]` - no `unsafe` in this crate.
47//! - Every object type preserves the byte-exact canonical-encoding round-trip
48//!   property (`decode(encode(x)) == x` and `encode(decode(b)) == b`).
49//! - Every `put` to a [`Blockstore`][store::Blockstore] verifies `cid == cid_of(bytes)`.
50//! - No panic on user input. All fallible paths return [`Error`].
51//!
52//! ## Status
53//!
54//! Core library, CLI, MCP, Python bindings, and retrieval surface are shipped.
55//! Remote protocol is next. See `docs/ROADMAP.md` for the current phase state
56//! and scope.
57//!
58//! [mnem]: https://github.com/Uranid/mnem
59
60#![forbid(unsafe_code)]
61#![deny(missing_docs)]
62#![cfg_attr(docsrs, feature(doc_cfg))]
63
64pub mod codec;
65pub mod error;
66pub mod guard;
67pub mod id;
68pub mod index;
69pub mod llm;
70pub mod objects;
71pub mod ppr;
72pub mod prolly;
73pub mod repo;
74pub mod rerank;
75pub mod resolve;
76pub mod retrieve;
77pub mod sign;
78pub mod sparse;
79pub mod store;
80
81pub use error::{Error, RepoError, Result};
82
83// Agent-facing retrieval shortcuts (re-exports so callers don't need
84// to reach into `mnem_core::index::*` paths for the common types).
85pub use index::{BruteForceVectorIndex, PropPredicate, Query, QueryHit, VectorHit, VectorIndex};
86pub use objects::{
87    Commit, Dtype, Edge, Embedding, EmbeddingBucket, EmbeddingEntry, IndexSet, Node, Operation,
88    RefTarget, View,
89};
90pub use repo::{ReadonlyRepo, Transaction};
91pub use retrieve::{
92    HeuristicEstimator, RetrievalResult, RetrievedItem, Retriever, TokenEstimator, render_node,
93};
94
95/// Library version (tracks the workspace package version).
96pub const VERSION: &str = env!("CARGO_PKG_VERSION");
97
98/// mnem format version this crate implements (see `docs/SPEC.md` §13).
99///
100/// Bumps when the on-wire object schema changes in a non-backward-compatible
101/// way. Pre-0.2 nodes are still decodable because new fields (e.g.
102/// `Node.summary` added in 0.2) are encoded with `skip_serializing_if`.
103pub const FORMAT_VERSION: &str = "mnem/0.2";
mnem_core/lib.rs

mnem_core/
lib.rs
