engram_consolidate
Run a memory consolidation cycle. Promotes important memories upward, drops decayed entries. With merge=true, uses LLM to merge similar memories.
LABSCO SUMMARY
Forgetting is the feature — a memory store that only grows becomes unusable.
Most agent memory is a flat pile with keyword search over it; here memories are promoted or decayed by how often they earn their keep, so what a session resumes with is a small set of things that survived rather than everything ever written. Two tools are worth building habits around: engram_triggers pulls the rules tied to an action before you take it, and engram_resume rebuilds a working context at the start of a session instead of leaving the model to search blind. Note that this is a client to a server you run yourself — nothing works until that binary is up.
What it is
A memory engine with a lifecycle. Memories move through three layers — Buffer, Working and Core — by access frequency and quality gating, so what matters is promoted and noise decays. It is a single Rust binary with one SQLite file behind an HTTP API, and this package is the MCP client to it.
What you get
- engram_store writes a memory with kind, tags, source, importance and namespace; supersedes replaces an earlier memory with history kept, and lessons auto-promote to Working after two hours
- engram_recall is hybrid semantic and keyword search with budget-aware retrieval — token budget, layer, tag, source and time filters, minimum score and importance — with optional LLM query expansion for vague queries
- engram_search is the lighter keyword-only path when scoring and budgeting are not needed
- engram_resume bootstraps a session: core knowledge, working context, buffer, recent activity and session notes, filterable by workspace tags
- engram_recent lists what was stored in the last N hours, for picking up where you left off
- engram_triggers fetches the memories attached to an action such as git-push or deploy — the lesson recalled before the mistake, not after
- engram_extract turns raw conversation logs or notes into individual structured memories
- engram_consolidate runs a promotion and decay cycle with thresholds you set, optionally merging similar memories
- engram_update and engram_delete revise or remove; engram_trash lists soft-deleted memories and engram_restore brings one back to its original layer
- engram_topic drills into the self-organising topic clusters, and engram_stats, engram_health and engram_repair cover layer counts, uptime and cache, and rebuilding the search index
Requirements
The engram server running — a single binary with a SQLite file, no Python, Redis or vector database, installed by its own script and listening on http://localhost:3917 by default. The MCP side runs as npx -y engram-rs-mcp with ENGRAM_URL pointing at that server, ENGRAM_API_KEY if it is behind bearer auth, and ENGRAM_NAMESPACE to keep projects separate. Semantic search needs an embedding provider, which the installer prompts for.
Setup effort
Follow the published steps — curl -fsSL https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.sh | bash
USE CASES
01
Picking a project back up after days away
Resume the session — core knowledge, ongoing context and recent activity in one call — instead of re-explaining the project.
02
Not repeating a mistake you already learned from
Before the risky action, fetch the memories tied to it — the lesson about deploys arrives before the deploy.
03
Turning a long conversation into something reusable
Extract structured memories from the transcript, then store the ones worth keeping with tags and importance.
04
Finding what you know about a topic
Search semantically within a token budget, filtered by layer, tag or time, and expand the query only when it is too vague to match.
05
Keeping the store from silting up
Run a consolidation cycle to promote what is used and drop what has decayed, merging near-duplicates as it goes.
06
Correcting something the memory got wrong
Update or supersede the memory so history is kept, delete what is simply wrong, and restore it from trash if you were too quick.
16 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
engram_delete
Delete a memory by ID. Use when a memory is outdated, incorrect, or redundant.
engram_extract
Extract structured memories from raw text using LLM. Feed conversation logs or notes and get individual memories.
engram_health
Detailed health check: uptime, RSS memory, embed cache stats, AI config status.
engram_recall
Hybrid semantic + keyword search with budget-aware retrieval. Fast by default (~30ms cached, ~1s first query). Optional expand adds LLM query expansion (+1-2s) — only use for short/vague queries.
engram_recent
List recent memories by creation time. Good for session context recovery.
engram_repair
Repair FTS search index. Removes orphaned entries and rebuilds missing ones. Safe to run anytime — idempotent.
engram_restore
Restore a soft-deleted memory from trash back to its original layer.
engram_resume
Full memory bootstrap for session recovery. Returns core (permanent knowledge), working (ongoing context/decisions), buffer (transient), recent activity, and session notes. Use workspace tags to filter by current work context. Compact mode (default) minimizes token usage.
engram_search
Quick keyword search. Lighter than recall — no scoring or budget logic.
engram_stats
Get memory statistics: counts per layer, AI status, version.
engram_store
Store a memory. All memories start in Buffer and promote to Working/Core through access frequency and LLM quality gating. Procedural memories and lessons (tag=lesson) auto-promote to Working after 2h. Use supersedes to replace outdated memories by their ids.
engram_topic
Drill into topic clusters by ID. Use after /resume to explore specific topics from the knowledge index.
engram_trash
List soft-deleted memories. Recently deleted items can be restored.
engram_triggers
Fetch trigger memories for a specific action. Call before performing an action (e.g. git-push, deploy) to recall relevant lessons and rules.
engram_update
Update a memory's content, metadata (importance, tags, layer, kind). Use supersedes on store to replace with history.
BEFORE YOU INSTALL
What to know first
Tools you get
16 tools when we connected; the project documents 17.
Requires
npx on PATH
Where it runs
All 4 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
curl -fsSL https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.sh | bash
npx engram-rs-mcpMCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add -s user engram -- npx -y engram-rs-mcpCursor, Windsurf, OpenClaw
JSON
{
"mcpServers": {
"engram": {
"command": "npx",
"args": [
"-y",
"engram-rs-mcp"
],
"env": {
"ENGRAM_URL": "http://localhost:3917",
"ENGRAM_API_KEY": "",
"ENGRAM_NAMESPACE": ""
}
}
}
}
