Crate mnemo_engine 

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_engine::{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

BuildInfo

Build-time cryptographic backend information.

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 (scoring v2, shipped in v0.7.0).

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.

Functions

build_info

Report this build’s cryptographic backend configuration.

Type Aliases

Result

Convenience result alias used throughout the crate.