Engram

Agent memory that knows when it's wrong.

Your agent remembers that codegraph is your primary tool. You uninstalled it six weeks ago. Nothing noticed — so every session since has opened by telling the model a confident, false thing about your own machine.

$ engram recall
mem-0001  [tooling]  codegraph is my primary code-graph tool

# six weeks later
$ engram remember "I uninstalled codegraph"
staged mem-0002: [tooling] I uninstalled codegraph
retired from recall pending review: mem-0001  (engram show <id> to resolve)

$ engram recall
$ engram queue
mem-0001  [tooling]  codegraph is my primary code-graph tool
          (superseded by mem-0002: 'codegraph' is reported gone, but this fact still asserts it)

Storing facts is the easy half. The half nobody does is noticing when a stored fact stops being true. The old fact isn't deleted — it drops out of recall and waits for you to rule on it.

One local store every agent reads from and writes to — plain Markdown you own, served over the Model Context Protocol. Works with Claude Code, Codex, opencode, and any MCP-capable client.

Status: early development. The core engine and MCP server are being built in the open. APIs will change.

Why

Coding agents forget everything between sessions. Every harness ships its own memory, none of them share, and all of them have the same blind spot: a fact, once stored, is treated as true forever. Memory that only accumulates doesn't get smarter — it gets more confidently wrong, and it degrades invisibly. Nothing errors. Recall keeps working. The facts just quietly stop being true.

Engram gives facts a lifecycle instead: captured, reviewed, recalled, contradicted, retired. You stay the gatekeeper for anything sensitive.

What it does and doesn't catch. Engram notices a contradiction when evidence arrives — a removal, a swapped value, two facts claiming one exclusive role — and expires facts on a decay horizon. It does not poll your machine to re-verify what it already believes. If a tool disappears and nothing ever captures that it's gone, only decay will catch it.

Related MCP server: Stoa

Your memory never leaves your laptop

Extraction runs against your model on your hardware — LM Studio, Ollama, or any OpenAI-compatible endpoint. There is no account, no server, no telemetry, and no cloud tier that eventually gets your data.

# ~/.config/engram/config.toml
[extractor]
base_url = "http://localhost:1234/v1"   # LM Studio
model = "qwen3.6-35b-a3b"

This is not a privacy mode you switch on. It is the only mode there is.

How it works

flowchart LR
    A["Any coding agent<br/>(Claude Code · Codex · opencode)"] -- "remember()" --> C
    T["Past session transcripts"] -- "harvest (local model)" --> C
    C{"engram<br/>capture + review"}
    C -- "low-risk kinds" --> M["memory.md<br/>★ source of truth"]
    C -- "sensitive kinds · conflicts" --> Q["review queue"]
    Q -- "promote --confirm" --> M
    C -- "promote --confirm" --> M
    M -- "contradicted by a newer fact" --> Q
    M -- "MCP resource · AGENTS.md / CLAUDE.md block" --> R["Recalled in every agent"]

• Capture — agents call a remember tool mid-task, or Engram harvests durable facts from session transcripts using a local model. Facts that only restate what's already stored, that anyone could read off a file path, or that name where your credentials live are refused before they're written.

• Review — low-risk kinds (you choose which) are logged automatically; sensitive kinds wait for your approval. Any promoted fact can be retracted with engram forget. Nothing rewrites your curated memory without consent.

• Recall — every agent loads your memories through an MCP resource or a generated AGENTS.md / CLAUDE.md context block.

A fact's journey. Your agent calls remember("prefers pnpm over npm", tooling). Every capture starts as pending — staged, not yet true. From there it reaches recall two ways: engram promote <id> --confirm approves it on the spot, or engram sync --apply walks the backlog and auto-appends the low-risk kinds while routing the sensitive ones to the review queue. tooling is low-risk, so sync would log it for you; remember("VAT number is 12345678X", fiscal) is not, so it waits for an explicit promote. Both end up as plain Markdown you can read, git diff, and engram forget.

Facts expire, so Engram retires them. When a new fact contradicts one already in recall — it claims the same exclusive role ("your primary editor"), or reports that something is gone — the older fact is marked superseded, dropped from recall immediately, and filed for review with the reason. It is never deleted, and the newcomer is not promoted in its place; you decide with promote or reject. Confidence also decays toward the fact's decay horizon, so a freshly confirmed fact outranks an older one that merely sounded more certain.

The lifecycle

stale and superseded are deliberately different: the first means time passed, the second means something newer disagreed. A sweep for the merely unconfirmed must not also retire the disputed.

Orthogonal to status, a fact may also have an envelope in queue/ — a review slip carrying the proposed destination and the reason it needs a human. sync files one when it escalates a candidate, and so does a contradiction. The envelope is context, never the source of truth: promote always reads the fact itself from memory.md, so editing the frontmatter of a queued fact does what you'd expect.

promote, reject and show all accept an id in any state awaiting your call — pending, stale, or superseded, queued or not. show and reject will also act on an already-decided fact; promote refuses one.

Where your memory lives

Everything is plain files in one folder — your store directory (default ~/.local/share/engram). The YAML frontmatter of memory.md is the single source of truth; every other surface is generated from it.

To change a fact, edit the frontmatter or use the CLI (remember / promote / forget) — don't hand-edit the generated body, it's overwritten on the next write. Because it's just files in a folder, your whole memory rides whatever already backs that folder up (Git, Dropbox, a NAS).

How recall stays fresh

Agents read your memory two ways. The memory://recall MCP resource is computed live on every call — always current. The CLAUDE.md / AGENTS.md block is a materialized view of that recall, for agents that only read a file at session start. With [recall] auto_refresh = true, Engram rewrites those blocks the instant promoted state changes (sync --apply, promote, forget), so a session always reads the latest; a daily gen-context job stays as a safety net. A block only lags if auto_refresh is off and you rely on the daily job alone. Full explanation: docs/RECALL.md.

How it compares

vs. a plain CLAUDE.md / instructions file

A CLAUDE.md is hand-written instructions for one tool — how an agent should behave. Engram is a harvested, reviewed knowledge base of facts about you — what's true — shared across every agent. They're complementary:

Use a CLAUDE.md for how to behave; use Engram for what's true about you — especially once you have more than one agent and facts you don't want auto-written.

vs. a typical memory tool

Most memory tools are vector stores the agent writes to directly. Engram takes a different stance:

Supported clients

Quickstart

Not yet on PyPI — install from source:

uv tool install git+https://github.com/xantorres/engram
# or: pipx install git+https://github.com/xantorres/engram
# or from a clone: uv tool install .

engram remember "I prefer pnpm over npm"    # stage a fact (pending review)
engram list --status pending                # see what's staged
engram promote mem-0001 --confirm           # approve one fact outright
engram recall                               # recall promoted memories
engram serve                                # start the MCP server for your agents

Working through a backlog with sync? Narrow it instead of processing everything at once:

engram sync                                  # dry run over the whole backlog
engram sync --id mem-0042 --id mem-0043      # just these two
engram sync --kind tooling --limit 25        # one kind, 25 at a time
ENGRAM_AUTOPROMOTE=true engram sync --kind tooling --limit 25 --apply

Wire it into an agent (Codex shown):

# ~/.codex/config.toml
[mcp_servers.engram]
command = "engram-mcp"

Design principles

• Facts expire. Contradiction, supersession and decay are the product, not maintenance bolted on later.

• Local-first. Your memories never leave your machine. No account, no telemetry.

• You own the data. Plain Markdown + YAML, git-diffable, no database lock-in.

• Human in the loop. Tiered writes: auto-log the trivial, gate the sensitive.

• Bring your own model. Any OpenAI-compatible endpoint extracts memories — cloud or local.

Documentation

• Quickstart

• Architecture

• How recall stays fresh

• Security and privacy

• Adapters

License

MIT