tokio-memory 0.2.1

Agent memory primitives: episodic, semantic, working memory with decay and consolidation, plus a durable SQLite store with full-text search
Documentation

tokio-memory

Start agent memory in-process today and move it to Postgres, SQLite or a vector DB later without changing agent code.

Why this over the alternatives: Every store is a trait with an in-memory implementation, so swapping the backend is a type change, not a rewrite.

Guarantee: if it doesn't do what this README says, open an issue and I'll fix it.

crates.io License: MIT

Trait-based memory building blocks for async Rust agents: an episodic store, a subject-predicate-object fact store, a query builder, Ebbinghaus-style decay, a pluggable episode-to-fact consolidation pipeline, a shared fact space with conflict resolution, and compact binary snapshots.

Each store is an async_trait (EpisodicStore, SemanticStore), so you can start with the in-memory implementations and later back them with Postgres, SQLite or a vector DB without changing agent code. Strongly typed ids (AgentId, SessionId, MemoryId, EntityId, Tag) keep agents and sessions from getting mixed up.

Features

Module What it does
episodic Episode (agent, session, EpisodeKind: Observation / Action / Inference / Interaction, content, strength, tags); EpisodicStore trait with record, recall, recall_range, recall_by_session, recall_by_tag, recall_by_agent; InMemoryEpisodicStore
semantic Fact triples (EntityId, predicate, FactValue::Text / Number / Bool, confidence); SemanticStore trait with assert_fact, retract_fact, query_subject; InMemorySemanticStore
retrieval MemoryQuery builder: filter by agent, session, tag, kind, since(duration), limit
decay DecayPolicy trait and ExponentialDecay with a configurable half-life
consolidation ConsolidationPolicy trait (decide and extract facts), FrequencyPolicy (strength threshold), ConsolidationPipeline::run_once
working WorkingBuffer: bounded priority buffer, pop_highest with FIFO tie-breaking
shared SharedSpace: namespaced, versioned facts with a ConflictResolver (LastWriteWins, HighestConfidenceWins, or your own)
persistence MemorySnapshot and encode_snapshot / decode_snapshot using postcard
sqlite (feature) SqliteMemory: both store traits in one SQLite file, so memory survives restarts, plus search (full-text, BM25-ranked) over episode content

Strength and confidence are validated to [0.0, 1.0] on construction, and property tests (proptest) cover decay bounds and snapshot round-trips.

Quick start

cargo add tokio-memory
cargo add tokio --features full
use std::sync::Arc;
use std::time::Duration;
use tokio_memory::consolidation::{ConsolidationPipeline, FrequencyPolicy};
use tokio_memory::episodic::{Episode, EpisodeKind, EpisodicStore, InMemoryEpisodicStore};
use tokio_memory::persistence::{decode_snapshot, encode_snapshot, MemorySnapshot};
use tokio_memory::retrieval::MemoryQuery;
use tokio_memory::semantic::{InMemorySemanticStore, SemanticStore};
use tokio_memory::{AgentId, MemoryError, SessionId, Tag};

#[tokio::main]
async fn main() -> Result<(), MemoryError> {
    let agent = AgentId::new();
    let session = SessionId::new();
    let episodic = Arc::new(InMemoryEpisodicStore::new());
    let semantic = Arc::new(InMemorySemanticStore::new());

    episodic.record(Episode::new(agent.clone(), session.clone(), EpisodeKind::Interaction,
        "user said they are vegetarian", 0.9, vec![Tag::new("preference")])?).await?;
    episodic.record(Episode::new(agent.clone(), session.clone(), EpisodeKind::Action,
        "opened the restaurants page", 0.3, vec![Tag::new("browsing")])?).await?;

    // Recall: last hour, this agent, tagged "preference".
    let prefs = MemoryQuery::new()
        .with_agent(agent.clone())
        .with_tag(Tag::new("preference"))
        .since(Duration::from_secs(3600))
        .limit(10)
        .execute(episodic.as_ref())
        .await?;
    println!("{} preference episode(s)", prefs.len());

    // Consolidate strong episodes into facts.
    let mut pipeline = ConsolidationPipeline::new(episodic.clone(), semantic.clone());
    pipeline.add_policy(Box::new(FrequencyPolicy::new(0.7)));
    let report = pipeline.run_once().await?;
    println!("{} episodes -> {} facts", report.episodes_processed, report.facts_extracted);

    // Snapshot everything to bytes and back.
    let snap = MemorySnapshot::new(agent, episodic.all().await?, semantic.all_facts().await?);
    let bytes = encode_snapshot(&snap)?;
    println!("snapshot: {} bytes, {} episodes", bytes.len(), decode_snapshot(&bytes)?.episodes.len());
    Ok(())
}

Durable memory with search (sqlite feature)

tokio-memory = { version = "0.2", features = ["sqlite"] }

SqliteMemory implements EpisodicStore and SemanticStore on a single SQLite file, so you can swap it in for the in-memory stores without touching agent code. SQLite is compiled into the crate (nothing to install), calls run on Tokio's blocking pool, and every episode is indexed with SQLite's FTS5 engine so an agent can find memories by what they say:

use tokio_memory::episodic::{Episode, EpisodeKind, EpisodicStore};
use tokio_memory::id::{AgentId, SessionId, Tag};
use tokio_memory::sqlite::SqliteMemory;

#[tokio::main]
async fn main() -> Result<(), tokio_memory::MemoryError> {
    let memory = SqliteMemory::open("agent-memory.db").await?;
    let (agent, session) = (AgentId::new(), SessionId::new());

    memory.record(Episode::new(agent.clone(), session.clone(), EpisodeKind::Observation,
        "User wants a window seat on the Lisbon flight", 0.9, vec![Tag::new("travel")])?).await?;
    memory.record(Episode::new(agent, session, EpisodeKind::Observation,
        "User is vegetarian", 0.8, vec![Tag::new("preference")])?).await?;

    // Next week, after a restart: what do we know about the flight?
    for (episode, score) in memory.search("lisbon flight", 5).await? {
        println!("{score:.2}  {}", episode.content);
    }
    Ok(())
}

Plain words are matched all-of, in any order; FTS5 syntax ("window seat", OR, NOT, veg*) works too. The feature needs Rust 1.85 (the rest of the crate builds on 1.79).

How it works

src/
  id.rs              MemoryId, AgentId, SessionId, NamespaceId, EntityId, Tag
  episodic/          Episode, EpisodicStore, InMemoryEpisodicStore (DashMap + insertion order), TimeRange
  semantic/          Fact, FactValue, SemanticStore, InMemorySemanticStore
  retrieval/query.rs MemoryQuery builder
  decay/             DecayPolicy, ExponentialDecay
  consolidation/     ConsolidationPolicy, FrequencyPolicy, ConsolidationPipeline
  working/buffer.rs  WorkingBuffer
  shared/            SharedSpace, VersionedFact, ConflictResolver implementations
  persistence/       MemorySnapshot, postcard codec
  sqlite.rs          SqliteMemory: SQLite tables + FTS5 index (feature `sqlite`)

Status and limitations

Version 0.2. Stores: in-memory, and SQLite with full-text search (sqlite feature). Retrieval filters on metadata (agent, session, tag, kind, time) and, with SQLite, on words; there is no embedding search yet. Decay policies compute strength but do not prune stores on their own.

For a sibling crate with causal event chains, a concept graph, fuzzy retrieval and a multi-agent broadcast bus, see tokio-agent-memory.

cargo test --all-features

License

MIT, see LICENSE.


Part of a set of Rust crates for LLM agents, see rust-crates.