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.

Structs

CompactReport

Result of a Mnemo::compact_file run.

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.

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

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.

Type Aliases

Result

Convenience result alias used throughout the crate.