Engram Rs

Memory engine for AI agents. Two axes:time(three-layer decay & promotion) andspace(self-organizing topic tree). Important memories get promoted, noise fades, related knowledge clusters automatically.

Most agent memory is a flat store — dump everything in, keyword search to get it back. No forgetting, no organization, no lifecycle. engram-rs adds the part that makes memory actually useful: the ability to forget what doesn't matter and surface what does.

Single Rust binary, one SQLite file, zero external dependencies. No Python, no Redis, no vector DB —curl | bashand it runs. ~10 MB binary, ~100 MB RSS, single-digit ms search latency.

# Install (interactive — will prompt for embedding provider config) curl -fsSL https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.sh | bash # Store a memory curl -X POST http://localhost:3917/memories \ -d '{"content": "Always run tests before deploying", "tags": ["deploy"]}' # Recall by meaning curl -X POST http://localhost:3917/recall \ -d '{"query": "deployment checklist"}' # Restore full context (session start) curl http://localhost:3917/resume

Inspired by theAtkinson–Shiffrin memory model, memories are managed across three layers by importance:

Buffer (short-term) → Working (active knowledge) → Core (long-term identity) ↓ ↓ ↑ eviction importance decay LLM quality gate

Buffer → [LLM gate: "Is this a decision, lesson, or preference?"] → Working Working → [sustained access + LLM gate] → Core

Decay is activity-driven — it only fires during active consolidation cycles, not wall-clock time. If the system is idle, memories stay intact.

Exponential decayfollows theEbbinghaus forgetting curve— fast at first, then long-tail. Memories never fully vanish (floor = 0.01), remaining retrievable under precise queries. When a memory is recalled, it gets anactivation boost, strengthening frequently-used knowledge.

"use PostgreSQL for auth" + "auth service runs on Postgres" → Merged into one, preserving context from both

Memory Architecture ├── Three-layer lifecycle [4] ├── Embedding pipeline [3] └── Consolidation logic [5] Deploy & Ops ├── CI/CD procedures [3] └── Production incidents [2] User Preferences [6]

The problem this solves: vector search requires asking the right question. Topic trees let agentsbrowse by subject— scan the directory, drill into the right branch.

Tag a memory withtrigger:deploy, and the agent can recall all deployment lessons before executing:

curl -X POST http://localhost:3917/memories \ -d '{"content": "LESSON: always backup DB before migration", "tags": ["trigger:deploy", "lesson"]}' # Pre-deployment check curl http://localhost:3917/triggers/deploy

Agent wakes up, callsGET /resume, gets full context back. No file scanning needed:

=== Core (24) === deploy: test → build → stop → start (procedural) LESSON: never force-push to main ... === Recent === switched auth to OAuth2 published API docs === Topics (Core: 24, Working: 57, Buffer: 7) === kb1: "Deploy Procedures" [5] kb2: "Auth Architecture" [3] kb3: "Memory Design" [8] ... Triggers: deploy, git-push, database-migration

Agent reads the directory, finds relevant topics, callsPOST /topicto expand on demand.

Semantic embeddings + BM25 keyword search with CJK tokenization (jieba). IDF-weighted scoring — rare terms get boosted, common terms auto-downweighted. No stopword lists to maintain.

# Semantic search curl -X POST http://localhost:3917/recall \ -d '{"query": "how do we handle auth", "budget_tokens": 2000}' # Note: min_score defaults to 0.30. Use "min_score": 0.0 to get all results. # Topic drill-down curl -X POST http://localhost:3917/topic \ -d '{"ids": ["kb3"]}'

Fully automatic, activity-driven — no writes means the cycle is skipped:
- Decay— reduce importance of unaccessed memories
- Dedup— merge near-identical memories (cosine > 0.78)
- Triage— LLM categorizes new Buffer memories
- Gate— LLM batch-evaluates promotion candidates
- Reconcile— resolve ambiguous similar pairs (results cached)
- Topic tree rebuild— re-cluster and name

Topic Distillation— when a topic grows too large (10+ memories), overlapping content is condensed into fewer, richer entries.

Single instance, multiple projects. UseX-Namespaceto isolate:

curl -X POST http://localhost:3917/memories \ -H "X-Namespace: my-project" \ -d '{"content": "API uses OAuth2 bearer tokens"}'

# macOS / Linux curl -fsSL https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.sh | bash # Windows (PowerShell) irm https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.ps1 | iex

docker run -d --name engram-rs \ -p 3917:3917 \ -v engram-data:/data \ -e ENGRAM_LLM_URL=https://api.openai.com/v1 \ -e ENGRAM_LLM_KEY=sk-... \ ghcr.io/kael-bit/engram-rs:latest

engram-rs works without an LLM — keyword search and rule-based lifecycle still function. Adding an LLM unlocks intelligent features (triage, gate, merge, topic naming):

export ENGRAM_LLM_URL=https://api.openai.com/v1 export ENGRAM_LLM_KEY=sk-... # Any OpenAI-compatible API (Ollama, LM Studio, etc.) export ENGRAM_LLM_URL=http://localhost:11434/v1 # Anthropic native export ENGRAM_LLM_PROVIDER=anthropic export ENGRAM_LLM_KEY=sk-ant-...

Two-tier model config — strong model for judgment, lightweight for text processing:

ENGRAM_GATE_MODEL=gpt-4o # quality decisions ENGRAM_LLM_MODEL=gpt-4o-mini # text processing

Set up engram-rs (persistent memory) by following the guide at: https://raw.githubusercontent.com/kael-bit/engram-rs/main/docs/SETUP.md

Works with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible tool.

17 MCP tools (MCP docs) | Full HTTP API (Setup guide)

# MCP (Claude Code) npx engram-rs-mcp # MCP (Cursor / Windsurf / generic) {"mcpServers": {"engram": {"command": "npx", "args": ["-y", "engram-rs-mcp"]}}}

Built-in web UI athttp://localhost:3917/uifor browsing memories, viewing the topic tree, and monitoring LLM usage.

Official Airtable MCP server and skills for working with bases, records, workflows, and business operations from AI agents.

MCP Server For Apache Doris, an MPP-based real-time data warehouse.

Official MCP Server from Atlan which enables you to bring the power of metadata to your AI tools

Query Onchain data, like ERC20 tokens, transaction history, smart contract state.

Read and write access to your Baserow tables.

Introspect and query your apps deployed to Convex.

Interact with the data stored in Couchbase clusters using natural language.

Maritime intelligence for tracking vessels, analysing ports, and exploring ship data.