Crate mnemo 

Mnemo

Mnemo is an encrypted, single-file, portable agent-memory engine.

A whole memory store — vectors, content, metadata, and the multi-signal recall machinery an agent needs — lives in one file you can copy, back up, or hand to another process. The file is encrypted at rest with a two-tier key hierarchy: an Argon2id key-encryption key (KEK) derived from a passphrase wraps a random data-encryption key (DEK), and the DEK encrypts every page with AES-256-GCM.

Quick start

use mnemo::{Mnemo, MnemoConfig, Memory, MemoryType, RecallRequest};

let cfg = MnemoConfig { dimensions: 3, ..Default::default() };
let mut db = Mnemo::create("agent.mnemo", "correct horse battery", cfg)?;

db.remember(
    Memory::new("the user prefers dark mode", MemoryType::Semantic, vec![0.1, 0.2, 0.9])
        .with_agent("assistant-1")
        .with_importance(0.8),
)?;
db.flush()?;

let hits = db.recall(&RecallRequest::new(vec![0.1, 0.2, 0.9]).top_k(5))?;
for h in hits {
    println!("{:.3}  {}", h.score, h.memory.content);
}

What is and is not built

This crate implements a real, tested core: the encrypted single-file storage engine, the crypto layer, the agent-memory model, multi-signal recall, an IVF+PQ approximate-nearest-neighbour index, a write-ahead log, snapshot-based point-in-time recovery, a bounded LRU page cache, and the Session conversation wrapper. Exact brute-force search remains available as the ground-truth baseline; a built index makes Mnemo::recall sub-linear. Each Mnemo::flush is one atomic, WAL-committed transaction and a restorable snapshot — Mnemo::restore_to rewinds the database to any past transaction. Python and TypeScript language bindings are the one documented roadmap item — see the README.

Modules

mcp

Hand-rolled Model Context Protocol (MCP) stdio server for MNemo.

Structs

CacheBudget

Per-namespace eviction budget. cache_put enforces both caps: on insert, the LRU is evicted until both live-entry count and live byte total fit under the caps.

CachePutOpts

Options accepted by Mnemo::cache_put. Defaults describe an untyped, never-expiring, non-cost-hinted entry.

CacheStats

Summary statistics for a namespace (or the whole cache).

CachedValue

A returned cache hit. accessed_at / access_count are updated on the directory before this is constructed, so the values here reflect the post-touch state (mirroring the recall-time convention).

CompactReport

Result of a Mnemo::compact_file run.

EmbedCmd

Persistent-child-process adapter for a user-supplied embedder command. See the module docs for the protocol.

EmbedderIdentity

Describe an embedder’s observable identity. Used both in-memory on an open [Mnemo] handle and persisted at metadata.embedder on the scaffold manifest so that reopening with a different embedder is caught at set_embedder time instead of silently polluting the index.

IndexConfig

Tuning knobs for building and querying an [IvfPqIndex].

IndexInfo

A read-only snapshot of an index’s shape, surfaced via Mnemo::stats.

KdfParams

Argon2id cost parameters. Stored (unencrypted) in the file header so the KEK can be re-derived on open.

Memory

A single memory entry.

Mnemo

An encrypted, single-file agent memory database.

MnemoConfig

Configuration for creating a new database.

RecallRequest

A retrieval request for Mnemo::recall.

RecallResult

One scored result from Mnemo::recall.

ScoreWeights

Weights for the multi-signal recall score.

SemanticCachePutOpts

Options for crate::Mnemo::cache_put_semantic. Same as CachePutOpts plus a required model string — a hit from a different embedding model’s cache is a semantics bug, not a win, so the engine forces callers to declare the model and matches it on lookup.

Session

A scoped conversation session over a Mnemo database.

SnapshotInfo

A restorable point in a database’s history — see Mnemo::snapshots.

Stats

Summary statistics for a database.

Turn

One conversation turn, written to working memory by Session::add_turn.

Ulid

Re-export of ulid::Ulid, the identifier type used for memories. A Ulid is a unique 128-bit lexicographically sortable identifier

Enums

CacheFlushPolicy

Per-handle flush policy for cache writes. Memory writes ignore this and always behave as Strict.

MemoryType

The four kinds of agent memory.

Metric

Distance/similarity metric for vector comparison.

MnemoError

All errors the Mnemo engine can produce.

Role

Who produced a conversation turn.

Scope

Visibility of a memory across agents sharing one .mnemo file.

Constants

DEFAULT_BATCH_MAX_AGE

Default max_age for CacheFlushPolicy::Batched.

DEFAULT_BATCH_MAX_DIRTY

Default max_dirty for CacheFlushPolicy::Batched.

DEFAULT_EMBED_TIMEOUT

Default per-request timeout. Set generously because a cold-start sentence-transformers call can genuinely take a few seconds the first time; configurable via EmbedCmd::with_timeout (Rust API) or the --embed-timeout CLI flag.

DEFAULT_MAX_BYTES

Default per-namespace byte budget (values + directory overhead). Once exceeded, cache_put evicts LRU until the total falls back under the cap.

DEFAULT_MAX_ENTRIES

Default per-namespace entry-count budget. Once a namespace holds this many live entries, cache_put evicts the LRU entry before inserting.

DEFAULT_SEMANTIC_THRESHOLD

Default similarity threshold for crate::Mnemo::cache_get_semantic. Lookups below this are treated as misses. Chosen conservatively to avoid false hits on subtly-different prompts; callers can override per-lookup. Model-dependent — text-embedding-ada-002 and BGE at this threshold rarely surface unrelated content, but if you’re working with a lossier embedder consider raising it.

Traits

Embedder

Minimal trait any embedder implementation must satisfy. Returns vectors in the same order as the input texts.

Type Aliases

Result

Convenience result alias used throughout the crate.