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.

[MIT License] [Python 3.9+] [PyPI] [CI]

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-studioengram connect all           # every supported app on this computerengram 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` commandengram 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 <token>. 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).

uv tool install engram-chateau     # or: pipx install engram-chateauengram init ~/myproject            # guided setup: your AI's identity, a default wing, then saves the project

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 migrated the app from SQLite to PostgreSQL on April 9" --reason "SQLite locked under concurrent writes"

From then on, search puts the current answer first and keeps the old one, clearly labelled, right below it:

$ engram search "which database does the app use"  1  c6e0b7b4       [current, replaces file-05aa607a] We migrated the app from SQLite to PostgreSQL on April 9…  2  file-05aa607a  [outdated → c6e0b7b4] Decision: the app stores everything in SQLite because…

engram history file-05aa607a shows the whole story: what it said, what replaced it, when, and why. Nothing is ever silently deleted. Old evidence stays searchable, and a mistaken correction can be undone with engram supersede <id> --undo.

Engram never decides by itself that one note contradicts another. Deciding what is true is the job of whoever is using it. When Claude saves a memory, Engram points out existing memories it might update, and Claude decides.

Why does it say that?

A memory can say what it rests on and where it came from, so a conclusion never floats free of its evidence:

engram source 903294e5 primary --ref "U.S. Const. art. I, § 2"   # where a memory came fromengram link c9422f65 based_on 903294e5 --reason "constitutional text"engram link c9422f65 derived_from 2da14213                       # also: contradicts, supersedes

Sources are user (you said it), primary (an original document, law, ruling or dataset), secondary (reporting or analysis), tool (a search or program result) and inference (an AI's own conclusion). Inferences stay labelled as inferences.

engram why <id> explains any memory: its source and date, whether it is a record or an inference, the evidence behind it, whether that evidence has since been corrected or disputed, earlier versions and their evidence, and, with --query, why search ranked it:

$ engram why c9422f65c9422f65-…  amy/views  2026-10-20  My view: population apportionment is the baseline; the 2025 map changes the state's representation.  Source: AI inference.  Type: an inference.
Evidence  based_on 903294e5  2026-10-20  primary source, U.S. Const. art. I, § 2    Article I, Section 2: Representatives shall be apportioned among the several States…  derived_from 2da14213  2026-10-20  secondary source  OUTDATED → 914e0cb2    Report: the legislature adopted a new map in 2025.
Needs review  • evidence 2da14213 was corrected (current version: 914e0cb2); check whether this still holds

engram check lists everything like that across your memory: conclusions whose evidence was corrected or disputed, inferences with no evidence, conflicts nobody has settled, links to deleted memories. It changes nothing. When a position is revised, the old one keeps the evidence it had, so you can always see what the earlier view rested on and what supports the new one.

Backups. engram export backup.json.gz puts every memory, correction, knowledge-graph fact and diary into one file. engram import backup.json.gz restores it on another computer, after checking the whole file first: if anything is wrong, nothing is changed. The format is documented in docs/backup-format.md.

How good is it?

Researchers test AI memory with two public benchmarks. Each gives the system long chat histories and asks questions whose answers are buried somewhere inside. The score is how often the system finds the right conversation.

In plain terms: ask Engram 500 questions about months of chat history, and for 494 of them the right conversation is in its top 5 results. It gets there with a small model that runs on a laptop, no LLM and no API. These tests measure finding the right conversation. They don't measure whether corrections, evidence links or recall notes make an AI more accurate; benchmarks/trust_eval.py checks those, and the results are listed below.

Does it keep memory trustworthy? Those tests don't cover corrections, the notes handed to a model, or crashes, so benchmarks/trust_eval.py checks them. On its own (author-written, deliberately small) scenarios, in the current version:

Auto-recall trades some answers for silence and small notes; the full table, what it doesn't show, and how to run it yourself are there. Nothing here shows that it makes an AI more accurate end to end; that hasn't been tested.

Should you use Engram?

There are several good memory tools. Here's an honest guide.

Use it in your own app

from engram.agents import AgentDiaryfrom engram.backends import get_backendfrom engram.chateau import Chateaufrom engram.knowledge_graph import KnowledgeGraphfrom engram.searcher import Searcher
memory = Chateau()                                   # your memory folder (~/.engram/chateau)searcher = Searcher(get_backend("chromadb"), memory)
for hit in searcher.search("what music does Maya like", n=5):    print(hit["text"], hit["final_score"])
AgentDiary("my-assistant").write("Helped plan the week")               # an agent's diaryKnowledgeGraph().add(subject="Maya", predicate="likes", obj="jazz")    # facts about people and things

These calls are pinned by tests/test_public_api.py, so apps built on them keep working across releases. For the full default search (exact-word index included), build the backend with engram.backends.backend_from_config(engram.config.load_config()).

Everyday commands

# Save thingsengram mine ~/project --wing myapp                 # a folder of filesengram mine ~/Downloads/claude-export --mode convos --wing myapp   # a Claude, ChatGPT or Slack exportengram watch ~/project --wing myapp                # keep saving as files change
# Find thingsengram search "auth decisions" --wing myappengram answer "What did we decide about the database?"   # a written answer (needs Ollama)engram replay --room auth-migration                # a topic's history, in order
# Fix and keep thingsengram correct <id> "the new, correct version"     # replace an outdated memory (old one kept as history)engram history <id>                                # what replaced what, when and whyengram why <id>                                    # where it came from, what it rests on, what changedengram forget <id>                                # delete a memory for good (shows what changes; add --yes)engram export backup.json.gz                       # back up everything to one fileengram import backup.json.gz                       # restore it (checked first; safe to repeat)
# Look after itengram status                                      # what's in your memoryengram wake-up                                     # the short start-of-session noteengram audit --fix                                 # health check and safe fixes

The ID is the short code in the first column of engram search results.

engram init <dir>                              # guided setupengram serve [--host H] [--port P] [--token]  # local web API for apps without MCP (OpenAPI at /openapi.json)engram reindex [--wing W]                      # rebuild the search index (after changing the embedding model)engram connect <app>                           # add Engram to Cursor, VS Code, Gemini CLI, Codex… (no app: list)engram install-hooks --apply                   # Claude Code hooks: auto-recall, auto-save, save before compactingengram recall "a message"                      # preview what auto-recall would give Claudeengram setup-reranker                          # download the reranker model (90 MB) and turn it onengram setup-reranker --disable                # turn the reranker off

engram mine <dir>                              # project filesengram mine <dir> --mode convos                # conversation exports (Claude, ChatGPT, Slack, Claude Code)engram mine <dir> --wing myapp --room auth     # choose the wing and roomengram mine <dir> --since 2026-01-01           # skip older filesengram mine <dir> --plugin obsidian            # also: notion, linearengram watch <dir> --wing myapp                # auto-save on changeengram split <dir> [--dry-run]                 # split concatenated transcriptsengram remember-type "Prefer SQLite for local dev" preference --wing myappengram remember-type --list                    # the 13 memory types

engram search "query" [--wing W] [--room R] [--results 20]engram search "query" --no-decay               # ignore recencyengram search "query" --no-hybrid              # meaning onlyengram search "query" --rerank / --no-rerank   # force the reranker on or off for one searchengram answer "question" [--wing W] [--model llama3.2] [--chunks 8]

engram wake-up [--wing W] [--rebuild]engram replay --room R [--wing W] [--type decision] [--since 2026-06-01] [--min-confidence 0.8]engram kg query "Kai" [--all]engram kg add "Kai" works_on "Orion" --from 2025-06-01engram kg invalidate "Kai" works_on "Orion" --ended 2026-03-01engram kg timeline "auth-migration"engram graph [--wing W] [--output file.png]   # needs: pip install "engram-chateau[viz]"

engram correct <id> "new text" [--reason "why"]  # save a correction that replaces <id>engram supersede <old-id> <new-id> [--reason R]  # mark an existing memory as replacing anotherengram supersede <old-id> --undo                 # make <old-id> current againengram history <id>                              # status and full replacement historyengram correct <id> "text" --source primary --ref "cite" --based-on <evidence-id>

engram forget <id>                                     # show what deleting it would changeengram forget <id> --yes                               # delete it, its search entries and every link to it

engram link <id> based_on <evidence-id> [--reason R]   # <evidence-id> supports <id>engram link <id> derived_from <other-id>               # <id> was inferred from <other-id>engram link <id> contradicts <other-id>                # conflict, undecidedengram link <id> supersedes <old-id>                   # <id> replaces <old-id>engram link <id> based_on <evidence-id> --undo         # remove a linkengram source <id> user|primary|secondary|tool|inference [--ref "citation or URL"]engram why <id> [--query "the question"] [--json]      # explain a memoryengram check [--json]                                  # what needs review; changes nothing

engram export <file>[.gz]                        # back up everything to one fileengram import <file> [--dry-run] [--overwrite]   # restore; the whole file is checked first

engram statusengram audit [--fix]engram conflicts                               # resolve contradicting knowledge-graph factsengram compress [--wing W] [--room R]          # rebuild short summaries (ES)engram provenance <drawer-id> [--history]engram provenance --summaryengram ui                                      # local notes app at http://127.0.0.1:7741

Settings

Everything works out of the box. If you want to tweak things, settings live in ~/.engram/config.json. Every key is optional, and the defaults are the benchmarked setup.

ENGRAM_VECTOR_BACKEND=sqlitevec engram … switches the backend for one run. An embedding server works with the default chromadb backend; each server and model keeps its own index, so switching back needs no reindex and your memories are never changed. ~/.engram/identity.txt holds the short identity that starts each wake-up note.

Troubleshooting

• engram: command not found after installing. pip put it somewhere not on your PATH. Use python3 -m pip install --user engram-chateau, or install with uv tool install engram-chateau / pipx install engram-chateau, which handle PATH for you.
• pip: command not found. Try pip3 or python3 -m pip. Inside a uv virtual environment, use uv pip install ….
• Moving to a new computer. Run engram export backup.json.gz on the old one, install Engram on the new one, then engram import backup.json.gz. Search indexes are rebuilt during the import.
• Claude doesn't show the engram tools. Restart Claude Code or Claude Desktop after adding the server. If the app can't find engram-mcp, give it the full path from which engram-mcp.
• "ChromaDB failed to load". ChromaDB's compiled parts don't match your Python. Try pip install --force-reinstall --no-cache-dir chromadb, or set "vector_backend": "sqlitevec", which needs no compiled parts. Then run engram mine again, because each backend keeps its own index.
• Python 3.15 or newer. ChromaDB can't install there yet, so Engram falls back to sqlitevec, which matches words rather than meaning. For meaning-based search, use Python 3.11 to 3.14.
• "No such command" after updating from GitHub. Run git pull origin main, then pip install -e . (or uv pip install -e .) in your Engram folder.
• The search Relevance column shows <0.001. The reranker found nothing that really answers that question; try a more specific one.

from engram.shorthand import compresscompress("The authentication module is a critical component that has a dependency on the database.")# → "auth module=★★ component +dep on db."

Requirements

• Python 3.9 or newer. 3.11 to 3.14 is recommended for meaning-based search.
• Installed automatically: ChromaDB, typer, rich, watchdog, questionary, pyyaml and requests.
• Optional extras: engram-chateau[faiss], [sqlitevec], [viz] (graph pictures) or [all].
• Optional: Ollama for engram answer.

Internet use: none, apart from two one-time downloads. The embedding model (about 80 MB) downloads the first time you save or search. The optional reranker (90 MB) downloads only if you run engram setup-reranker. Your memories never leave your machine.

Contributing

Bug reports, ideas and pull requests are welcome.

git clone https://github.com/TushaeBXN/engram && cd engrampip install -e ".[dev]"pytest

Credits and license

Engram's design (wings, rooms, halls, drawers and a temporal knowledge graph) is inspired by other open-source memory systems. Some retrieval ideas (the exact-word index and date understanding) are adapted from Hindsight.

MIT © 2026 Tushae Thomas

If Engram helps you remember something that mattered, a ⭐ helps other people find it.