bge-reranker-base before the budget pack, with graceful fallback to the fused order on any failure and a rerank_enabled opt-out. Measured on the committed gold-set (same harness as the model fly-off): full stack recall@5 0.90 → 1.00, MRR@10 0.78 → 0.95, nDCG@10 0.83 → 0.96 — 9 of 10 queries now rank the right memory first; scope/temporal calibration unchanged. Floors frozen and gated in CI. Wired into engram context pack, the MCP server, and the web Context Preview; dual code + security review. Plus a persistent embedding cache (~/.engram/cache/embeddings.db, content-addressed, LRU, fully degrading) so a one-shot CLI call re-embeds only changed bodies, and a remote backend (backend = remote, stdlib urllib: OpenAI-compatible embeddings + Cohere/Jina/Voyage rerank) sharing the observer's reviewed key-allowlist and redirect-stripping discipline. 1456 tests, ruff + mypy strict green. Curated metadata in the lexical channel (T-218, 2026-07-29): a memory's hand-written name and description were invisible to retrieval; indexing them lifted BM25 MRR@10 0.670 → 0.764 and the fused channel 0.781 → 0.858 on the committed gold-set, with calibration untouched. The interesting half is what we did not ship: feeding the same metadata to the embedder cost 0.056 MRR@10 on LOCOMO and 0.139 on its temporal questions, because those generated descriptions all carry a date and every asset became slightly date-relevant. BM25 has IDF to discount corpus-wide text; dense retrieval does not. Metadata that is safe to index is not automatically safe to embed. A variant that also feeds the cross-encoder scored a perfect 1.000/1.000/1.000/1.000 and is still unshipped — its LOCOMO arm is unmeasured. 1522 tests, ruff + mypy strict green.
Join the discussion
engram is a local, portable, LLM-agnostic memory system that grows smarter with use. Plain markdown on your disk. Any model, any tool — you own it forever.
docs/assets/demo.gif — the transcript above is the same flow.
Switch models, lose context. Switch tools, re-teach from scratch. engram is the opposite design.
Memory locked inside a proprietary SQLite database. Switch to another model — context gone.
Memories stored in the vendor's cloud. No export, no git diff, no portability across tools.
Memory lives as human-readable .md files on your disk. Any LLM, any editor, git-friendly — forever.
Each layer is replaceable in isolation. Remove any layer above Layer 1 and the system keeps working correctly.
Classes are distinguished by function — what the asset is — not by size. No hard line limits.
One fact, rule, preference, or pointer that can be independently superseded. The baseline for LLM context priming.
Structure: single .md + YAML frontmatter
Role: loaded into system prompt via Relevance Gate
No size cap — adaptive signals replace fixed thresholds
Has a runnable spine, fixture test cases, and a metrics tracker. Not just a description — it must actually execute.
Structure: workflow.md + spine.* + fixtures/ + metrics.yaml
Role: loaded on task match; Autolearn Engine evolves it
Autolearn tracks outcomes and proposes improvements
Multi-chapter document a human would read deliberately. LLM compiles a _compiled.md digest for efficient context loading.
Structure: README.md + chapters + assets/ + _compiled.md
Role: digest enters budget first; full chapters fetched on demand
Human writes; LLM compiles digest
Three adaptive signals replace hard size caps: dynamic budget allocation · percentile length signal · split/promote/demote proposals from the Evolve Engine
Real teams share knowledge in more than one way. engram separates membership hierarchy from topic subscription into two independent axes.
The Consistency Engine runs a four-phase scan and surfaces proposals. It never auto-executes changes.
factual-conflict
rule-conflict
reference-rot
workflow-decay
time-expired
silent-override
topic-divergence
never mutates
Engine proposes, never mutates. Deletions always flow through archive/ with a minimum 6-month retention floor before physical removal.
Your agents often work on multiple related repos in parallel. When agent A spots a bug in repo B, it can send a structured inbox message — without interrupting B's session.
The combination no other system attempts: data-asset portability + active quality maintenance + quantifiable self-improvement.
| Capability | engram v0.2 | claude-mem | basic-memory | Karpathy Wiki | mem0 | MemGPT / Letta | ChatGPT Mem |
|---|---|---|---|---|---|---|---|
| Plain markdown storage | ✓ open | SQLite | ✓ | ✓ gist | hosted | hosted | hosted |
| Tool-agnostic (any LLM) | ✓ | Claude only | partial | partial | partial API | partial API | ChatGPT only |
| Two-axis scope (hierarchy + pool) | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Explicit enforcement levels | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Consistency detection (7 classes) | ✓ | partial | ✗ | ✗ | ✗ | ✗ | ✗ |
| Executable workflows | ✓ | ✗ | ✗ | ✗ | ✗ | partial | ✗ |
| Knowledge Base class | ✓ | ✗ | ✗ | ✓ manual | ✗ | ✗ | ✗ |
| First-class Web UI | ✓ | ✗ | ✗ | ✗ | partial hosted | partial hosted | partial hosted |
| MCP server | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Cross-repo inbox | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Quantified self-improvement | ✓ Wisdom Metrics | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Open source | ✓ MIT | ✓ | ✓ | ✓ | partial | ✓ | ✗ |
Four quantitative curves prove the store self-improves. "It feels more useful" becomes a number that can regress or improve.
Workflow Mastery
Task Recurrence Efficiency
Memory Curation Ratio
Context Efficiency
Track via engram wisdom report — each curve computed from recorded outcomes, not heuristics.
The store belongs to its owner, not the tool that writes it. Any text editor. Any LLM. Any version control system.
Boring markdown wins decade-scale bets. The format is the permanent commitment; the intelligence layer is the optional investment.
No cap on how much you store. Strict bar on quality. The Consistency Engine keeps the store coherent as it grows.
Deletions flow through archive/ with a minimum 6-month retention floor. Every retirement requires an explicit decision.
Memory confidence is computed from recorded outcomes, not vibes. The system retires bad memories because it has data that they're bad.
v0.2 CLI is under active construction. M2 scaffold landed 2026-04-20 — clone, pip install -e "cli[dev]", then engram --version. Subcommands roll out through M2–M4. SPEC + DESIGN are open for review in parallel.
pip install engram-cli
engram init --subscribe=kernel-work --adapter=claude-code,codex
engram web serve # open http://127.0.0.1:8787engram init --org=acme --team=platform \
--subscribe=compliance-checklists,kernel-work,design-system \
--adapter=claude-code,codex,geminiclaude # reads CLAUDE.md → reads .memory/
codex # reads AGENTS.md → reads .memory/
engram mcp serve # for Claude Desktop, Zed, any MCP client
engram context pack --task="fix auth flow" --budget=4k | ollama run qwen:7bengram review # aggregate health check
engram consistency scan # detect conflicts, suggest resolutions
engram wisdom report # see the four self-improvement curvesSPEC Freeze
SPEC + DESIGN v0.2 frozen — 14 chapters each; external review open
Core CLI
done — full CRUD + validate + review, 15 tasks
Scope + Pool
done — full 2-axis scope, pool subscription, v0.1→v0.2 migrate
Intelligence + Auto-Continuation
done — Relevance Gate, Consistency Phase 1–3, MCP, 5 adapters, 4-tier auto-continuation (T-200–T-212)
Workflow + Autolearn
Workflow asset class shipped — spine / fixtures / rev. Autolearn ratchet still open
KB + Inbox
KB class + inbox roundtrip & reverse-notify + Consistency Phase 3. Phase 4 staleness pending
Web UI
done — stdlib server-rendered, 6 read-only P0 pages, no node/build step
Full Evolve + SDK
next: benchmark-driven retrieval (RRF / rerank), Evolve Engine, TypeScript SDK
On every task the Relevance Gate decides which memories enter the context budget. How well it ranks them is the product's core quality — so retrieval is measured against a frozen benchmark and only allowed to improve. It runs on plain keywords by default; an optional model adds semantic and cross-lingual matching when you want it.
Lexical ranking in pure stdlib. No model, no download, no extra dependency — the shipped default, instant and offline.
Enough when the query shares words with the memory.
Blind spot: "how do we ship to prod" won't match a note titled "blue-green rollout"; a Chinese query won't match an English note.
Shipped · the zero-dependency baseline
A small multilingual embedding model plus a cross-encoder reranker, run locally via ONNX — no PyTorch, no API key, no network. It catches paraphrases and cross-lingual matches the keyword path misses, then reranks the top hits by reading query and memory together.
Turn on with pip install engram[ml].
Models pinned by id + revision, so the benchmark stays reproducible.
Opt-in · landing in M8, benchmark-gated
The same two stages served by an endpoint you choose — Ollama on your own machine, or OpenAI / Cohere / Voyage. No local download; the trade is a network call and sending text off-device.
For teams already running an embedding endpoint.
Default off. Endpoints scheme-validated; keys read from env, never logged.
Opt-in · planned, M8 fast-follow
Graceful by default: if no model is configured or a provider is unreachable, retrieval falls back to keyword search for that query. The base install stays pure-stdlib — the model is a capability you opt into, never a dependency you inherit.
Each prior project shaped one specific piece of engram.
LLM-compiled knowledge compounds in value over time. Inspired the Knowledge Base class and the compilation step.
Eight-discipline agentic self-critique loop. Shaped the Autolearn Engine's evolution cadence for Workflow assets.
Experience as executable code, not text. The founding insight behind the Workflow asset class with its runnable spine.
Search → Synthesize → Evolve lifecycle. ReMem action-think-refine loop drives the Evolve Engine's memory proposals.
Ebbinghaus curve for LLM memory. Adapted to evidence-driven confidence scoring rather than time-based decay.
Memory as OS virtual memory. Inspired the Layer 1 tiered data structure — without the managed-service requirement.
The direct precursor engram generalizes. Proved the value of LLM-adjacent markdown memory in practice.
Retrieval algorithm research informing the Relevance Gate's candidate ranking pipeline.
The SPEC and DESIGN are open. For open-ended talk on the scope model, asset-class boundaries, Consistency Engine taxonomy, or your use case — join Discussions. For concrete bug reports and feature requests, file an Issue.
Issues tracks concrete tasks — each one has a clear actionable outcome. For open-ended discussion, head to Discussions.
File an Issue