mnem-core 0.1.0

Content-addressed versioned substrate for AI agent memory - the core of mnem.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

//! # mnem-core
//!
//! The core library for [mnem] - a content-addressed, versioned substrate for
//! AI agent memory.
//!
//! This crate contains the format types, canonical encoding, content hashing,
//! Prolly-tree algorithms, operation-log machinery, and repository API.
//!
//! ## Scope
//!
//! `mnem-core` is deliberately factored to be embeddable in every runtime.
//! It has:
//!
//! - No terminal I/O (`println!`, `eprintln!` are forbidden inside this crate)
//! - No config-file loading (callers supply config; we consume it)
//! - No direct filesystem access - storage is behind the [`Blockstore`][store::Blockstore] trait
//!   (implemented in `mnem-backend-redb` or callers' own backends)
//! - No `tokio` runtime binding (sync API; async wrappers live in callers)
//!
//! These constraints are what make the same source compile to native binaries,
//! WASM, and FFI-consumed libraries in Python / Node / Go.
//!
//! ## Modules
//!
//! - [`id`] - identity primitives: `Multihash`, [`Cid`][id::Cid], stable
//!   [`NodeId`][id::NodeId] / [`EdgeId`][id::EdgeId] /
//!   [`ChangeId`][id::ChangeId] / [`OperationId`][id::OperationId], and
//!   phantom-typed [`Link<T>`][id::Link].
//! - [`codec`] - canonical DAG-CBOR encode/decode and DAG-JSON debug export.
//! - [`objects`] - [`Node`], [`Edge`], [`Commit`], [`Operation`], [`View`],
//!   [`IndexSet`] types. Prolly tree chunks live under [`prolly::TreeChunk`].
//! - [`prolly`] - Prolly tree algorithms (chunker, builder, lookup, cursor,
//!   diff, merge).
//! - [`store`] - [`Blockstore`][store::Blockstore] and
//!   [`OpHeadsStore`][store::OpHeadsStore] traits, plus in-memory
//!   reference implementations.
//! - [`repo`] - [`ReadonlyRepo`], [`Transaction`] facade.
//! - [`index`] - secondary indexes ([`Query`],
//!   [`BruteForceVectorIndex`]).
//! - [`retrieve`] - agent-facing [`Retriever`] that composes filters,
//!   vector and sparse ranking, and token-budget packing.
//! - [`sign`] - Ed25519 signing and revocation-list verification.
//!
//! ## Crate-level invariants
//!
//! - `#![forbid(unsafe_code)]` - no `unsafe` in this crate.
//! - Every object type preserves the byte-exact canonical-encoding round-trip
//!   property (`decode(encode(x)) == x` and `encode(decode(b)) == b`).
//! - Every `put` to a [`Blockstore`][store::Blockstore] verifies `cid == cid_of(bytes)`.
//! - No panic on user input. All fallible paths return [`Error`].
//!
//! ## Status
//!
//! Core library, CLI, MCP, Python bindings, and retrieval surface are shipped.
//! Remote protocol is next. See `docs/ROADMAP.md` for the current phase state
//! and scope.
//!
//! [mnem]: https://github.com/Uranid/mnem

#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod codec;
pub mod error;
pub mod guard;
pub mod id;
pub mod index;
pub mod llm;
pub mod objects;
pub mod ppr;
pub mod prolly;
pub mod repo;
pub mod rerank;
pub mod resolve;
pub mod retrieve;
pub mod sign;
pub mod sparse;
pub mod store;

pub use error::{Error, RepoError, Result};

// Agent-facing retrieval shortcuts (re-exports so callers don't need
// to reach into `mnem_core::index::*` paths for the common types).
pub use index::{BruteForceVectorIndex, PropPredicate, Query, QueryHit, VectorHit, VectorIndex};
pub use objects::{
    Commit, Dtype, Edge, Embedding, EmbeddingBucket, EmbeddingEntry, IndexSet, Node, Operation,
    RefTarget, View,
};
pub use repo::{ReadonlyRepo, Transaction};
pub use retrieve::{
    HeuristicEstimator, RetrievalResult, RetrievedItem, Retriever, TokenEstimator, render_node,
};

/// Library version (tracks the workspace package version).
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// mnem format version this crate implements (see `docs/SPEC.md` ยง13).
///
/// Bumps when the on-wire object schema changes in a non-backward-compatible
/// way. Pre-0.2 nodes are still decodable because new fields (e.g.
/// `Node.summary` added in 0.2) are encoded with `skip_serializing_if`.
pub const FORMAT_VERSION: &str = "mnem/0.2";