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.
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
use Arc;
use Duration;
use ;
use ;
use ;
use MemoryQuery;
use ;
use ;
async
Durable memory with search (sqlite feature)
= { = "0.2", = ["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 ;
use ;
use SqliteMemory;
async
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.
License
MIT, see LICENSE.
Part of a set of Rust crates for LLM agents, see rust-crates.