Skip to main content

Engram

A memory engine for AI agents: typed memories, budget-bounded recall, timely forgetting, and contradiction adjudication.

Open source (MIT) · TypeScript · 67 unit tests across 6 files, all green · Qwen Cloud Global AI Hackathon 2026 (Track 1: MemoryAgent), judging in progress.

The problem

Agents forget everything between sessions, or paper over it by stuffing the whole chat history into context. Cost then grows without bound, stale facts linger, and contradictory facts coexist silently. Engram treats memory as an engineering problem in the three parts most memory demos skip: selection (what is worth recalling this turn under a hard token budget), forgetting (what should stop being recalled, and when), and truth maintenance (what happens when new information conflicts with old).

Engram stores typed memories (preference, fact, skill, episode), each with its own decay half-life, and an LLM scores importance at write time so low scorers are observed but never stored. Recall ranks active memories by a blend of embedding similarity, retention, importance, and access frequency, then greedily packs them under a hard token budget. Forgetting is Ebbinghaus-style: below a retention floor a memory is marked decayed, excluded from recall but never deleted, so the audit trail survives. When new information conflicts with old, the nearest active memories are adjudicated with strict JSON and fail-safe parsing that never supersedes on a parse error. A live memory board surfaces every engine decision, and the same engine is exposed over the Model Context Protocol as a memory backend any agent can adopt.

Quickstart

Engram is an MCP server: point any MCP-capable agent at it and get a long-term memory backend instead of dumping raw history into context. Node with pnpm; the unit tests run with no network and no API key.

Clone and install:

git clone https://github.com/OrionArchitekton/engram
cd engram
pnpm install

Command surface

  • pnpm dev: The memory board: write memories, run recall under a budget, and watch every engine decision (recalled, stored, not stored with score, superseded, decayed).
  • pnpm mcp: Runs the MCP server over stdio, exposing engram_remember, engram_recall, and engram_list so any MCP-capable agent can adopt Engram as its long-term memory backend.
  • pnpm test: 67 unit tests across 6 files: the Qwen client, retrieval, consolidation, the store, the MCP tools, and contradiction handling, with zero network calls.
  • engram_remember / engram_recall / engram_list: The three MCP tools an adopting agent calls: write a typed memory, recall the best memories packed under a hard token budget, and list what is currently retained.

Why it is different

  • Memory as an engineering problem: Most memory demos stop at storing and fetching text. Engram takes on the three parts they skip: selection under a hard budget, timely forgetting, and truth maintenance when facts conflict. Those are the parts that decide whether an agent stays cheap, current, and consistent over time.
  • Budget-bounded recall: Active memories are ranked by a blend of embedding similarity, retention, importance, and access frequency, then greedily packed under a hard token budget. The packer provably never exceeds the budget, which is property-tested rather than asserted, so recall cost has a ceiling instead of growing with history.
  • Timely forgetting, never deletion: Retention decays Ebbinghaus-style. Below a floor a memory is marked decayed and drops out of recall, but it is never deleted, so the audit trail of what the agent once knew survives. Forgetting here means stops being recalled, not lost.
  • Contradiction adjudication, fail-safe: When new information conflicts with old, the nearest active memories are adjudicated with strict JSON at temperature zero. The parser is fail-safe: on a parse error it never supersedes an existing memory. Conflicts resolve to a superseded marker with a pointer to the replacement, not a silent overwrite.
  • Adopt it as a memory backend over MCP: The same engine is exposed over the Model Context Protocol. Any MCP-capable agent points at the Engram server and gets engram_remember, engram_recall, and engram_list, with budget-bounded recall, decay, and contradiction handling included, instead of dumping raw history into its context window.

Links