Skip to main content

Crate cortex_rs_memory

Crate cortex_rs_memory 

Source
Expand description

§relay-memory

license

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.

Structs§

DecayReport
MemoryStore
WriteOptions