Crate umi_memory 

Umi Memory

A production-ready memory library for AI agents with deterministic simulation testing.

Features

• 🧠 Smart Memory Management: Core, working, and archival memory tiers with automatic eviction
• 🔍 Dual Retrieval: Fast vector search + LLM-powered semantic query expansion
• 🔄 Evolution Tracking: Automatically detect updates, contradictions, and derived insights
• ✅ Graceful Degradation: System continues operating even when LLM/storage components fail
• 🎯 Deterministic Testing: Full DST (Deterministic Simulation Testing) for reproducible fault injection
• 🚀 Production Backends: LanceDB for embedded vectors, Postgres for persistence

Quick Start

use umi_memory::umi::{Memory, RememberOptions, RecallOptions};

// Create memory with simulation providers (deterministic, seed 42)
let mut memory = Memory::sim(42);

// Remember information
memory.remember(
    "Alice is a software engineer at Acme Corp",
    RememberOptions::default()
).await?;

// Recall information
let results = memory.recall("Who works at Acme?", RecallOptions::default()).await?;

for entity in results {
    println!("Found: {} - {}", entity.name, entity.content);
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Memory Orchestrator                   │
├─────────────────────────────────────────────────────────┤
│  EntityExtractor  │ DualRetriever  │ EvolutionTracker   │
├─────────────────────────────────────────────────────────┤
│  Core Memory (32KB)      │ Always loaded, persistent   │
│  Working Memory (1MB)    │ TTL-based eviction, cache   │
│  Archival Memory         │ Vector search + storage     │
├─────────────────────────────────────────────────────────┤
│  DST Framework           │ Fault injection + simulation│
└─────────────────────────────────────────────────────────┘

Core Components

• Memory - Main orchestrator, coordinates all components
• EntityExtractor - Extracts structured entities from text
• DualRetriever - Fast + semantic search with RRF merging
• EvolutionTracker - Detects memory evolution patterns

Simulation-First Philosophy

“If you’re not testing with fault injection, you’re not testing.”

Every component has a deterministic simulation implementation:

use umi_memory::dst::{Simulation, SimConfig, FaultConfig, FaultType};

let sim = Simulation::new(SimConfig::with_seed(42))
    .with_fault(FaultConfig::new(FaultType::LlmTimeout, 0.1));

sim.run(|env| async move {
    // Test code with deterministic fault injection
    // Same seed = same faults = reproducible bugs
    Ok::<_, anyhow::Error>(())
}).await.unwrap();

Feature Flags

• lance - LanceDB storage backend
• postgres - PostgreSQL storage backend
• anthropic - Anthropic LLM provider (Claude)
• openai - OpenAI LLM provider (GPT, embeddings)
• llm-providers - All LLM providers
• embedding-providers - All embedding providers

Examples

See the examples directory for:

• quick_start.rs - Basic remember/recall workflow
• production_setup.rs - Production configuration
• configuration.rs - Custom memory settings

Documentation

• GitHub Repository
• Architecture Decision Records
• Development Guide

Re-exports

pub use dst::create_simulation;

pub use dst::run_property_tests;

pub use dst::test_seeds;

pub use dst::DeterministicRng;

pub use dst::FaultConfig;

pub use dst::FaultInjector;

pub use dst::FaultType;

pub use dst::NetworkError;

pub use dst::NetworkMessage;

pub use dst::PropertyTest;

pub use dst::PropertyTestFailure;

pub use dst::PropertyTestResult;

pub use dst::PropertyTestable;

pub use dst::SimClock;

pub use dst::SimConfig;

pub use dst::SimEnvironment;

pub use dst::SimNetwork;

pub use dst::SimStorage;

pub use dst::Simulation;

pub use dst::StorageError;

pub use dst::TimeAdvanceConfig;

pub use memory::ArchivalMemory;

pub use memory::ArchivalMemoryConfig;

pub use memory::CoreMemory;

pub use memory::CoreMemoryConfig;

pub use memory::CoreMemoryError;

pub use memory::MemoryBlock;

pub use memory::MemoryBlockId;

pub use memory::MemoryBlockType;

pub use memory::WorkingMemory;

pub use memory::WorkingMemoryConfig;

pub use memory::WorkingMemoryError;

pub use storage::Entity;

pub use storage::EntityBuilder;

pub use storage::EntityType;

pub use storage::SimStorageBackend;

pub use storage::StorageBackend;

pub use llm::CompletionRequest;

pub use llm::LLMProvider;

pub use llm::ProviderError;

pub use llm::SimLLMProvider;

pub use embedding::EmbeddingError;

pub use embedding::EmbeddingProvider;

pub use embedding::SimEmbeddingProvider;

pub use extraction::EntityExtractor;

pub use extraction::ExtractedEntity;

pub use extraction::ExtractedRelation;

pub use extraction::ExtractionError;

pub use extraction::ExtractionOptions;

pub use extraction::ExtractionResult;

pub use retrieval::DualRetriever;

pub use retrieval::RetrievalError;

pub use retrieval::SearchOptions;

pub use retrieval::SearchResult;

pub use evolution::DetectionOptions;

pub use evolution::DetectionResult;

pub use evolution::EvolutionError;

pub use evolution::EvolutionTracker;

pub use umi::Memory;

pub use umi::MemoryError;

pub use umi::RecallOptions;

pub use umi::RememberOptions;

pub use umi::RememberResult;

pub use constants::*;

Modules

constants

TigerStyle Constants

dst

DST - Deterministic Simulation Testing

embedding

Embedding Provider Trait - Unified Interface for Text Embeddings

evolution

Evolution Tracking - Memory Relationship Detection (ADR-016)

extraction

Entity Extraction - LLM-powered entity and relation extraction

llm

LLM Provider Trait - Unified Interface for Sim and Production

memory

Memory - Core and Working Memory for Umi

retrieval

Dual Retrieval - Fast search + LLM reasoning

storage

Storage - Backend Trait and Implementations

umi

Umi Memory - Main Interface (ADR-017)