Engram

Engram

Your AI forgets everything when the chat ends. Engram helps it remember.

Free, private, runs on your own computer, and keeps every word exactly as you wrote it.

---

The problem

On Monday you spend an hour with Claude working out why the login system leaks memory, and you decide to switch libraries. On Friday you open a new chat and ask *"why did we drop Passport again?"*

It has no idea. The conversation is gone, and so is the reasoning.

The same thing happens with everything you tell an AI: your sister's birthday, the bug you already fixed, the reason a setting is the way it is. Every new chat starts from zero.

Engram is a memory that outlasts the chat. It saves your notes, files and conversations, and when you ask a question later, it finds the right one, even if you phrase it completely differently.

---

See it work

Two ordinary notes go in:

notes/decisions.md   We switched from Passport to Lucia on March 3 because

Passport sessions kept leaking memory under load. notes/personal.md My sister Maya's birthday is June 14. She loves anything with sunflowers.

engram mine notes --wing life

Days later, ask in your own words. None of these questions share a sentence with the notes:

$ engram search "why did we change the auth library"

1 life/notes We switched from Passport to Lucia on March 3 because Passport sessions kept leaking memory under load.

$ engram search "gift idea for Maya" 1 life/notes My sister Maya's birthday is June 14. She loves anything with sunflowers.

Hook it up to Claude and it does this by itself: Claude looks things up in Engram when it needs them, and Engram saves your Claude Code sessions automatically.

---

Try it in 2 minutes

You need Python 3.9 or newer (3.11 to 3.14 is best). Check with python3 --version.

1. Install

pip install engram-chateau

On PyPI the package is called engram-chateau, but the command you type is just engram. (A different, unrelated package already owns the name engram.)

2. Give it something to remember

engram mine ~/Documents/notes --wing notes      # any folder of notes, docs or code

The first run downloads a small language model (about 80 MB) that lets Engram understand meaning. After that, everything works offline.

3. Ask it something

engram search "what did I decide about the database"

That's all you need to try it.

Connect it to your AI app

Engram works with any app that speaks MCP, the standard way AI apps plug in tools. One command adds it:

engram connect cursor        # or: claude-desktop, windsurf, vscode, gemini, codex, zed, lm-studio

engram connect all # every supported app on this computer engram connect # list them, with ✓ next to the ones you have

It adds Engram to that app's settings (keeping everything else, with a .bak backup) and tells you how to restart the app. Run it again any time; it changes nothing the second time.

Every app then has 31 engram_* tools: recall, search, remember, correct an outdated memory, link a conclusion to its evidence, explain why a memory says what it says, a topic's history, a knowledge graph of people and facts, and more. On connect, Engram also tells the AI how to use them: check memory before answering anything that depends on past work, save decisions, and correct rather than contradict. (Apps decide whether to pass that guidance to the model; most current ones do.) Ask *"remember that we use tabs in this repo"*, *"what did we decide about auth?"* or *"we moved to PostgreSQL, update that"*.

Claude Code gets the most: memory that works without being asked.

engram connect claude-code        # prints the one-line `claude mcp add` command

engram install-hooks --apply # then restart Claude Code

install-hooks adds three Claude Code hooks to ~/.claude/settings.json (your existing settings are kept, with a backup):

• Auto-recall. Each time you send Claude a message, Engram searches your memory first. If something clearly relevant turns up, Claude gets a short note with up to 3 memories before it answers, current versions first (with what they replaced and why) and outdated ones labelled. You ask *"why did we drop Passport?"* in a brand-new chat, and Claude already knows. Nothing is added when nothing is relevant, a memory isn't repeated within a session, and it takes about a second once warm (the first message after your computer starts it can take several seconds while it loads).
• Project-aware. Memories are filed under the project you're working in (the git repo or folder name), and recall shows that project's memories first; other projects' notes only appear when they match very closely.
• Auto-save. Every file Claude edits is saved.
• Save before compacting. The conversation is saved before Claude Code compacts it.

Preview what auto-recall would hand Claude with engram recall "your message". Run engram install-hooks without --apply to see the settings instead of applying them, or add --no-recall to skip auto-recall.

Any other MCP app: point it at the command engram-mcp (or python -m engram.mcp_server). Engram is also listed in the official MCP registry as io.github.TushaeBXN/engram.

Apps that don't speak MCP (Open WebUI, n8n, your own scripts) can use Engram over a small local web API:

engram serve                  # http://127.0.0.1:7742, the same tools and rules as MCP

Point the app at http://127.0.0.1:7742/openapi.json; every tool is described there. Or call it directly:

curl -s localhost:7742/v1/tools/engram_recall -H 'Content-Type: application/json' \

-d '{"message": "why did we drop Passport?"}'

Memories are private, so it is strict by default. It listens on localhost only, and refuses requests that look like they come from a web page or through a proxy. To reach it from another machine, use engram serve --host 0.0.0.0: that always requires a token (created on first use in ~/.engram/server/token, never printed), sent as Authorization: Bearer . engram serve --token requires one even on localhost. No CORS headers are ever sent, so a web page can't talk to it.

Teach any coding agent to use it. skills/engram/SKILL.md is a ready-made agent skill: when to recall, save and correct, and how to explain a conclusion. Install it with npx skills add TushaeBXN/engram (or copy the file).

Prefer uv, pipx or a guided setup?

uv tool install engram-chateau     # or: pipx install engram-chateau

engram init ~/myproject # guided setup: your AI's identity, a default wing, then saves the project

Both put engram and engram-mcp on your PATH without touching your system Python.

---

Who it's for

🧑💻 Developers using Claude Code. Engram quietly saves the files Claude touches and the conversations behind them. Months later, *"why is the retry limit 7?"* brings back the actual discussion, not a guess.

🤖 People building an AI companion or agent. Give your bot a memory of its own: what it has learned about you, a diary, and a knowledge graph of people and facts (*"Kai works on Orion, since June"*). It all runs offline in a few lines of Python. Engram started life as exactly this, the memory of a personal companion app.

📚 Writers, researchers and note-takers. Point it at a folder of notes, an Obsidian vault, or Notion or Linear exports, and search across all of it by meaning: *"that idea I had about pricing tiers"*.

---

Why Engram is different

• 🔒 It's yours. Everything lives in one folder on your computer (~/.engram/). No account, no cloud, no API key, no tracking.
• 📝 It keeps your words. Most AI memory tools have an LLM rewrite your conversations into short "facts" and throw the original away. Engram stores the original text and finds it again. Nothing gets lost in a summary.
• 🧠 It understands what you mean. It finds *"we switched from Passport to Lucia"* when you ask about *"changing the auth library"*. It also matches exact names and numbers (INV-20931), and understands time: *"two weeks ago"*, *"in June"*, *"on May 8"*.
• 💸 It's free to run. It needs no LLM to save or search, so there are no per-message costs and nothing to rate-limit.
• 🎯 It's accurate. On the two standard tests of AI memory, it beats the best published no-LLM results (numbers below).
• 📖 You can read all of it. About 10,000 lines of plain Python, MIT licensed. If you want to know exactly what happens to your data, you can.
• 🔄 It knows when it's out of date. When a decision changes, the new memory is marked as replacing the old one. Search gives you the current answer first, and the old one stays below it as history, with when and why it changed.
• 🔑 It can hide secrets for you. Turn on redact_secrets and API keys, tokens and passwords are blanked out before anything is written to disk.

---

How it works

Engram files memories the way you'd organise a big house: one wing per person or project, a room per topic, a hall per kind of memory, and inside, drawers holding the original text.

Wing   – a person or project        ("myapp", "life")

└── Room – a topic ("auth-migration") └── Hall – the kind of memory (facts, events, discoveries, preferences, advice) └── Drawer – your original text, word for word

You don't have to manage any of this; Engram sorts things as it saves them. When you search, it weighs several clues together:

At the start of a session, Engram can also hand the AI a small "wake-up" note (who it is plus key facts: pinned ones first, then the newest, about 120 tokens by default), so it never starts completely cold.

---

When things change

In March you note that the app stores everything in SQLite. In April you move to PostgreSQL. Most memory tools now hold two contradicting notes and return whichever matches the question best.

In Engram, you (or Claude, or your agent) record the change once:

engram correct file-05aa607a "We