Engram

The memory-trace layer for agents. Make any agent loop learn from its own runs.

Every multi-attempt agent today throws its raw trajectory back into context on retry — burning tokens and degrading quality. The June-2026 research frontier showed the fix is to inject a distillate of what happened, not the transcript, and to bank reusable conclusions across tasks. Engram is that layer, framework-agnostic and dependency-free.

Built directly on two results:

• RTV + PDR — Scaling Test-Time Compute for Agentic Coding (arXiv 2604.16529). Compress each rollout into hypotheses + failures + leads; vote across attempts (Recursive Tournament Voting); condition the next attempt on the distillate (Parallel-Distill-Refine). +12 pts on Terminal-Bench v2.0.
• TMAS two-bank memory — Scaling Test-Time Compute via Multi-Agent Synergy (arXiv 2605.10344). One bank of reliable conclusions, one of meta-strategies, shared across runs.

Why

The bottleneck on hard agent tasks is not the model — it's that agents don't reuse what they already learned. Engram gives them a memory trace: compress → bank → recall → select.

Use it as an MCP server (no code)

Engram ships an MCP server, so any agent that speaks MCP — Claude Code, Claude Desktop, Cursor — gets cross-session memory without you writing a line.

{
  "mcpServers": {
    "engram": { "command": "node", "args": ["/abs/path/to/engram/mcp.mjs"] }
  }
}

Clone-and-point for now; the npm package name is agent-engram, not yet published. (engram, engram-mcp and engram-memory are all taken on npm by unrelated authors — worth knowing before you go looking for this by name.)

Five tools:

tool	when the agent calls it
engram_recall	first, on any non-trivial task — returns a priors block to paste into its own reasoning
engram_ingest	when a task ends, succeeded or failed — compresses the trajectory and banks the durable parts
engram_compress	to hand a long transcript to another model without paying for the whole thing
engram_note	to bank one fact or strategy directly, no trajectory needed
engram_stats	how much is banked, and where on disk

Memory is JSON under ~/.engram-store (override with ENGRAM_STORE). Nothing leaves the machine.

What Engram banks, and one measured negative result

Two kinds of thing come out of a finished run, and Engram keeps them in separate banks per TMAS:

• "The auth token lives in .env.local" — a conclusion, true about this codebase.
• "When a test fails on CI but not locally, diff the env first" — a strategy, true about how to work, and reusable on a task that has nothing to do with auth.

Failed runs are worth more than successful ones here. ingest turns each failure into an avoid-strategy carrying its root cause, which is the difference between the next session solving something and rediscovering it.

The honest part. The obvious argument for the split is that in one undifferentiated pile the codebase-specific conclusions out-match the transferable strategy on keywords and crowd it out of the top-k. I tested that claim against this implementation before writing it down, at 10:1, 13 items, and 200:5 conclusions-to-strategies. It did not hold. The single pile surfaced the same strategy, at rank #1 in two of the three runs — because TF-IDF's IDF term already boosts an item whose vocabulary is rare in the corpus, which is exactly what a lone strategy among many similar conclusions looks like.

So the split here buys structural things — a guaranteed recall budget for strategies, the ability to ask for one kind without the other, and fidelity to the paper — and not a retrieval win I can demonstrate. Reproduce it yourself: node bench/two-bank.mjs. If you find a store shape where the split does win, that is a genuinely interesting issue to open.

Install

# zero runtime dependencies; Node 18+
npm install   # nothing to build — pure ESM
npm test      # node --test
npm run demo  # offline, deterministic

Use

import { Engram } from 'agent-engram';

const engram = new Engram({ store: './engram-store' });

// 1. Recall priors before an attempt — inject the block into your prompt.
const priors = engram.recallPriors('Fix the failing checkout test');
// priors.block  ->  "# Relevant priors from past runs ..."

// 2. Learn from a finished attempt.
await engram.ingest({
  goal: 'Fix the failing checkout test',
  steps: [
    { type: 'error',  content: 'TypeError: total is undefined — cart was empty' },
    { type: 'result', content: 'Guard added: default cart to [] before reducing.' },
  ],
  outcome: 'success',
});

// 3. Or hand Engram the whole loop: it runs N attempts and selects the best.
const { winner } = await engram.solve(
  'Fix the failing checkout test',
  async (priorsBlock, attempt) => myAgent.run({ context: priorsBlock }),
  { attempts: 3 },
);

Step types

A trajectory is an array of { type, content }. Types: thought, action, observation, error, result. The compressor routes errors → failures (with root cause), results → artifacts, actions → leads, thoughts → hypotheses.

Model-backed compression (optional)

By default compression is deterministic and offline. Pass an llm to let a model write richer distillates:

const engram = new Engram({
  store: './engram-store',
  llm: async (prompt) => callYourModel(prompt), // returns the JSON distillate
});

API

Call	Does
recallPriors(goal)	TF-IDF recall from both banks → { block, conclusions, strategies, tokens }
ingest(run)	Compress a run, bank its conclusions + strategies, return the distillate
compress(run)	Compress only (no banking)
solve(goal, runner, { attempts })	Run N attempts, tournament-select the winner, learn from it
compressTrajectory(run)	Standalone trajectory → distillate
MemoryBank	Standalone two-field TF-IDF memory store
tournament(candidates, judge?)	RTV selection over distillates

License

MIT.