Crate mnem_core 

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 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, stable NodeId / EdgeId / ChangeId / OperationId, and phantom-typed Link<T>.
• 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 and 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 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.

Re-exports

pub use error::Error;

pub use error::RepoError;

pub use error::Result;

pub use index::BruteForceVectorIndex;

pub use index::PropPredicate;

pub use index::Query;

pub use index::QueryHit;

pub use index::VectorHit;

pub use index::VectorIndex;

pub use objects::Commit;

pub use objects::Dtype;

pub use objects::Edge;

pub use objects::Embedding;

pub use objects::EmbeddingBucket;

pub use objects::EmbeddingEntry;

pub use objects::IndexSet;

pub use objects::Node;

pub use objects::Operation;

pub use objects::RefTarget;

pub use objects::View;

pub use repo::ReadonlyRepo;

pub use repo::Transaction;

pub use retrieve::HeuristicEstimator;

pub use retrieve::RetrievalResult;

pub use retrieve::RetrievedItem;

pub use retrieve::Retriever;

pub use retrieve::TokenEstimator;

pub use retrieve::render_node;

Modules

codec

Canonical encoding and decoding of mnem objects.

error

Top-level error type for mnem-core.

guard

Shared commit-budget guard primitive (gap-catalog shared/commit-budget-guard).

id

Identity primitives for mnem.

index

Secondary indexes and the Query engine (Phase 2).

llm

Text-generation trait for HyDE and multi-query retrieval .

objects

Canonical object types: Node, Edge, Tree, Commit, Operation, View.

ppr

Personalized PageRank over an AdjacencyIndex.

prolly

Prolly tree - content-defined Merkle-tree index .

repo

Repository facade - the user-facing entry point to mnem.

rerank

Reranker trait: post-fusion rescoring by a model that jointly encodes (query, candidate) pairs.

resolve

Entity canonicalization - resolve_or_create (gap-catalog gap 04).

retrieve

Agent-facing retrieval: compose structured filters, dense vector similarity, and learned-sparse retrieval under a token budget.

sign

Ed25519 signing + revocation-list verification (SPEC §9).

sparse

Sparse (learned) embedding primitives for SPLADE / BGE-M3-sparse integration .

store

Storage-layer traits and reference implementations.

Constants

FORMAT_VERSION

mnem format version this crate implements (see docs/SPEC.md §13).

VERSION

Library version (tracks the workspace package version).