Mnemoria

Mnemoria is a memory storage system for AI agents. It provides persistent, searchable memory that AI assistants can use to remember information across conversations and sessions. Perfect for Claude, GPT, Cursor, or any AI tool that needs long-term context.

Library Usage

use mnemoria::{Mnemoria, EntryType};
use std::path::Path;

#[tokio::main]
async fn main() -> Result<(), mnemoria::Error> {
    // Create a new memory store
    let memory = Mnemoria::create(Path::new("./my-memories")).await?;

    // Store a memory
    let id = memory.remember(
        "my-agent",
        EntryType::Discovery,
        "Rust async patterns",
        "Use tokio::spawn for CPU-bound work inside async contexts",
    ).await?;

    // Search by meaning (hybrid BM25 + semantic)
    let results = memory.search_memory("async concurrency", 5, None).await?;
    for result in &results {
        println!("[{}] {} (score: {:.3})", result.entry.entry_type, result.entry.summary, result.score);
    }

    // Retrieve by ID
    let entry = memory.get(&id).await?;
    Ok(())
}

Support this project

If this project has been helpful to you, you are welcome to sponsor it. Sponsorship helps me spend more time maintaining it, fixing bugs, and building new features.

No pressure at all - starring the repo, sharing it, or giving feedback also means a lot.

Become a sponsor

Features

• Semantic Search - Find memories by meaning, not just keywords
• Full-Text Search - BM25-powered keyword search
• Hybrid Search - Combines both approaches via Reciprocal Rank Fusion
• Git-Friendly - Append-only binary format, version control safe
• Corruption Protection - CRC32 checksum chain with crash recovery
• Unlimited Size - Only bounded by disk space

Installation

Prerequisites

• Rust (stable toolchain)
• ~130MB for embedding model (downloaded on first use)

Build from Source

# Clone the repository
git clone https://github.com/one-bit/mnemoria
cd mnemoria

# Build and install
cargo install --path .

Via crates.io

cargo install mnemoria

Quick Start

# 1. Initialize a new memory store in the current directory
mnemoria init

# Or specify a path
mnemoria --path /path/to/project init

# 2. Add a memory entry
mnemoria add --type discovery \
  --summary "Found optimal async pattern for file I/O" \
  "Use tokio's fs::File with spawn_blocking for CPU-intensive work..."

# 3. Search your memories  
mnemoria search "async file operations"

# 4. Ask questions about your memories
mnemoria ask "what async patterns have I discovered?"

Commands

Entry Types

When adding memories, you can categorize them:

• intent - Goals and intentions
• discovery - Things you learned
• decision - Decisions made
• problem - Problems encountered
• solution - Solutions found
• pattern - Recurring patterns
• warning - Warnings to remember
• success - Successes/outcomes
• refactor - Refactoring notes
• bugfix - Bug fixes applied
• feature - Features implemented

Git Usage

Mnemoria uses an append-only binary format designed for version control. You can commit your mnemoria/ directory directly to track memory history alongside your code:

# Track memories in git (recommended for most projects)
git add mnemoria/
git commit -m "add project memories"

For large memory stores, use Git LFS:

git lfs track "mnemoria/log.bin"
git add .gitattributes mnemoria/

If you prefer not to track memories in version control:

echo "mnemoria/" >> .gitignore

Storage Format

mnemoria/
├── log.bin           # Append-only binary log
├── manifest.json     # Metadata and checksums
└── mnemoria.lock     # Advisory file lock

The search index is rebuilt on each open and is not stored in git.

Architecture

• Storage: rkyv binary serialization (zero-copy)
• Full-Text: Tantivy (BM25)
• Embeddings: model2vec (512-dim, CPU-only)
• Similarity: simsimd (SIMD-accelerated)

Performance

Benchmarks run with Criterion.rs (cargo bench --bench api_perf). Results below are median values.

Test Environment

Search Latency (hybrid: BM25 + semantic via RRF)

Write Throughput (200-entry batches)

Get by ID

Timeline

To run benchmarks yourself:

cargo bench --bench api_perf

License

MIT License. See LICENSE for details.

Repository

https://github.com/one-bit/mnemoria