relay-memory

Tiered memory engine with semantic embeddings, FTS5 hybrid retrieval, and Weibull decay.

Overview

relay-memory stores facts and retrieves them via hybrid search: full-text (FTS5) combined with semantic similarity (all-MiniLM-L6-v2 embeddings). Memories are organized in tiers (hot, warm, cold) and decay nightly using a Weibull distribution, promoting or demoting entries based on access patterns and confidence scores. Conflicts are detected via SHA-256 hashing of content, and embeddings can be backfilled from earlier versions.

Usage

Add as a dependency:

[dependencies]
relay-memory = { path = "../relay-memory" }
relay-core = { path = "../relay-core" }

Example:

use cortex_rs_memory::{MemoryStore, WriteOptions};
use cortex_rs_core::Db;
use std::path::Path;

fn main() -> anyhow::Result<()> {
    let db = Db::open(Path::new("/Users/me/.cortex/memory.db"))?;
    let store = MemoryStore::new(db);
    
    // Write a memory
    let memory = store.write(
        "prefer named exports in TypeScript",
        WriteOptions::default(),
    )?;
    
    // Recall by keyword + semantic match
    let results = store.recall("exports", 5)?;
    println!("Found {} memories", results.len());
    
    // Get hot-tier context for session preamble
    let hot = store.hot_context()?;
    println!("Hot memories: {:?}", hot);
    
    Ok(())
}

Public API

• MemoryStore::new(db) - initialize the store
• MemoryStore::write(content, opts) - save a new memory
• MemoryStore::recall(query, limit) - hybrid FTS5 + semantic search
• MemoryStore::hot_context() - fetch top hot-tier memories
• MemoryStore::pin(id) - mark a memory to bypass decay
• MemoryStore::decay_pass() - promote/demote tiers nightly
• MemoryStore::backfill_embeddings(batch) - populate embeddings for old memories
• MemoryStore::open_conflicts() - fetch unresolved conflict pairs
• WriteOptions - builder for write behavior (pinned, confidence, etc)

Dependencies

• relay-core - types, database, config
• rusqlite - SQLite queries
• fastembed - ONNX embedding model (all-MiniLM-L6-v2). Optional, gated behind the embeddings feature flag which is on by default. Disable with --no-default-features for FTS5-only builds.
• sha2 - hash-based conflict detection
• chrono - timestamps

Part of Relay

relay-memory is one of six MIT-licensed pillar crates. It can be used standalone in other projects that need tiered semantic memory with decay. Relay also includes relay-core (schema and types), relay-notes (wikilinks), relay-router (task classification), relay-stats (cost tracking), and relay-miner (pattern mining). The three architecture crates (relay-mcp, relay-daemon, relay-cli) compose all pillars into the MCP server.

See the workspace README and LICENSING.md for details.

License

MIT. See LICENSE.