engram-rs is a memory engine designed for AI agents, aimed at solving the problems of traditional agent memory: "flat storage, only growing and never shrinking, and lack of organization." It manages memory along two axes: the time axis handles three-tier decay and promotion, and the space axis handles a self-organizing topic tree. The project is delivered as a single Rust binary, uses one SQLite file, has zero external dependencies, requires no Python, Redis, or vector database, and can be run via curl | bash. The binary is about 10 MB, memory usage is about 100 MB, and search latency is in the single-digit millisecond range.
Main Capabilities
Three-Tier Lifecycle
Inspired by the Atkinson–Shiffrin memory model, memories are managed across three tiers according to importance:
- Buffer: the entry point for all new memories, temporarily staged, and evicted when below a threshold.
- Working: promoted through consolidation, never deleted, with importance decaying at different rates by type.
- Core: promoted through an LLM quality gate, never deleted.
LLM Quality Gate
Promotion is not a rule-based guess, but rather an LLM evaluating each memory in context to determine whether it is truly worth retaining long term.
Automatic Decay
Decay is activity-driven and triggered only during active consolidation cycles, not by wall-clock time. When the system is idle, memories remain unchanged. Exponential decay follows the Ebbinghaus forgetting curve, fast at first and then with a long tail. Memories do not disappear completely (the floor is 0.01) and can still be retrieved under exact queries. When a memory is recalled, it receives an activation boost, reinforcing frequently used knowledge.
Semantic Deduplication and Merging
Two memories that express the same content in different wording are automatically detected and merged.
Self-Organizing Topic Tree
Vector clustering groups related memories, and the LLM names the clusters, with no manual tagging required. This solves the problem that vector search requires asking the right question: the topic tree lets agents browse by topic—scan the directory and drill down into the right branch. For example, by tagging memories with trigger:deploy, an agent can recall all deployment experience before execution.
Session Recovery
After waking up, an agent can call GET /resume to retrieve the full context without scanning files. The agent reads the directory, finds relevant topics, and calls POST /topic to expand them on demand.
Search and Retrieval
Semantic embeddings plus BM25 keyword search, with support for CJK tokenization (jieba). IDF-weighted scoring—rare words are boosted, common words are automatically downweighted, with no need to maintain a stopword list.
Background Maintenance
Fully automatic and activity-driven—cycles are skipped if there are no writes. Consolidation runs every 30 minutes and includes: decay (lowering the importance of unaccessed memories), deduplication (merging near-identical memories, cosine similarity > 0.78), classification (LLM classifying new Buffer memories), gating (LLM batch-evaluating promotion candidates), reconciliation (resolving ambiguous similar pairs, with results cached), and topic tree reconstruction (reclustering and naming). Topic distillation: when a topic grows too large (more than 10 memories), overlapping content is condensed into fewer, richer entries.
Namespace Isolation
A single instance supports multiple projects, using X-Namespace for isolation.
LLM Configuration
engram-rs works without an LLM—keyword search and the rule-based lifecycle remain available. Adding an LLM unlocks intelligent features (classification, gating, merging, topic naming). Two levels of model configuration are supported: a strong model for judgment and a lightweight model for text processing.
Usage
The project provides 17 MCP tools and a complete HTTP API. The built-in Web UI is located at http://localhost:3917/ui，用于浏览记忆、查看主题树和监控 LLM usage. Can be used with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible tool. Installation is via curl | bash.
Use cases
Suitable for AI agents that need long-term memory, automatic forgetting, and knowledge organization, for example agent applications that need to remember deployment experience, session context, and project knowledge and automatically organize topics.
Limitations
The materials do not provide specific system requirements, supported platforms, a list of LLM providers, detailed data on performance benchmarks, licensing agreements, or pricing information.
