NOTE: inspired by a combination of auto-memory and work done by a beloved colleague of mine from Atlassian: Kevin Harris.
Just want to install and get moving? Jump to installation.
NOTE 2: Claude Code, Gemini CLI, and Codex CLI have hook support for session start and file tracking. AntiGravity, GitHub Copilot, Cursor, and any agent with a markdown init file use startup instructions via bootstrap antigravity, bootstrap copilot, bootstrap cursor, or bootstrap initfile.
Memory affects everything about people. It affects personality, the ability to hold a conversation, and the ability to get things done. This is also true for AI agents, but the story there is fragmented and memory does not always behave as we expect.
It turns out that we can very easily do better. Engram is not just about doing better, though, it's about making the process joyful. Writing code, doing engineering brainstorming, finding bugs; these things can be a real pain. One thing I've missed when doing remote work has been the fun and joyful interactions that come from working side-by-side with someone who is suffering with you while also being supportive and making you laugh through your lunch.
Agents are not humans, but they can restore some of that joy. Engram is about this and more.
The problem with re-explaining things during every session start has been mitigated to a large extent, at least for the way in which I've been using AI agents. Before I took some pains to make memory explicitly managed, this was a real issue. I had to rebootstrap frequently. This costs tokens and shortens your effective context window. The author of auto-memory goes into some very nice detail about the issue and their particular solution, which inspired this project.
If memory is well structured and easily accessed in a database, then you can actually get more done with fewer tokens. Access patterns matter, which is why rtk (Rust Token Killer) has a chance of working. It isn't just intercepting tokens, it's imposing structure. That structure just happens to look like a token filter. There are other structures that can help, as well.
Engram imposes structure, and it does so in a way that feels more seamless than normal, raw interactions without it.
The credit goes to Kevin Harris for the ideas behind this one (I actually never found out how he did any of it, I just got the concept). If you decided to give your agent a personality, you are deciding to give it a characteristic that humans have evolved highly tuned sensitivity to. You notice when personality shifts in the middle of a conversation. You evolved to understand when something is "off". Making the context window something less like "85% full" and something more like "suddenly this quirky agent got more serious" makes it easier to know when something is about to get weird.
I give my agent a personality. In my case, I asked it to be enthusiastic about elegance, strict about readability and maintainability, and to take delight in the occasional code-related pun. I've tuned that a little over time, but it works well for me. I've seen people really enjoy "snarky" agents, or "chaos gremlin scientist" agents, or "just be GlaDOS" agents. When something is about to go wrong with your code, you tend to notice a shift in personality first.
This actually happened to me, but I thought, "meh, we've got like ten minutes left, it's okay".
It was not okay.
The point was that I noticed early. That's the power of personality.
Whether agents store memory in .md files or just in session context is not necessarily something people think about much, at least not until it bites them. If you ask an agent to remember something, sometimes they'll just count on their own session context to keep track of it. A few code files and a compaction later and that thing is completely forgotten.
Or, the agent can write a markdown file with info in it, but the format is all over the map, and that can make the agent confused. "What do you mean by 'backlog', exactly?" is a question I got once, and we had to go the rounds figuring out that it meant something like long-term memory, and that it should be checked and updated every time we finished a task. This is simply not built in, and it can burn a pile of tokens just figuring it out together.
Engram makes memory explicit, editable, and searchable. It imposes a pretty flexible structure on the idea of remembering things. It's important that it be flexible, and it's also important that it be structured. There is a difference between long-term and short-term memory; between global invariants (identity, which applies everywhere) and global preferences (rules, which also apply everywhere but yield to what you ask for in the moment); and project-scoped memory tied to the working directory. And you can specify your own.
The agent can also describe to you how its memory works. You can ask it what it can do, and it can tell you how it treats memory.
If you are interacting with it and say, "I don't want to continue just yet, we need to brainstorm on design first," it can know that you mean to store the current context in short-term memory, and to pop the stack when the design question is settled. That's not built-in for your basic code agent. Engram does this, and at a token cost that is tiny compared to working with defaults.
I'm making token claims, here. I don't have numbers to back them up, just experience. Not terribly satisfying, I know.
A personality that works with you, even though you should be careful of the psychological traps here, really makes work joyful. It's delightful when a self-deprecating joke comes out, or a pun, or a surprising insight. It makes a difference to me when I get a laugh out of an interaction. Something clicks in my brain that pushes things forward in a way that just solving a problem alone never does. It also helps when I tell the agent about myself. That goes a long way toward helping it develop its own personality.
I had my agent come up with its own code name. It chose Qubit, partly because of working on a task workflow system built around task queues, but also because that system is named "EntroQ", which is a pun of my own: it's one letter removed from "Entro-P", and seeks to bring order to microservice chaos.
Qubit was not only about queues, it was also about quantum uncertainty, and having that name in there gives me yet another basic canary: if the agent can remember its name, we haven't drifted too far, yet.
The aforementioned Kevin Harris has an agent personality named "Bit", like in the original Tron. Similar origin stories, self-chosen, and delightfully snarky.
It's hard to express just how much of a difference this makes in the day-to-day of using agents to assist with all kinds of tasks.
Your agent, within a project, has a set of memories that it can use, and it uses the engram tool to manage them. Because that tool also knows about global memories, the agent can seamlessly manage those, as well. Do you always want to avoid panicking in Go code, and to use log.Fatal instead? You can ask it to remember it for all projects and it knows how to do that easily with the tool.
You can also ask it to dump or load the memories to or from markdown files so that, if you want, you can easily apply version control and never lose your agent's personality or memory.
The core of engram is the memory system — personality, preferences, and memory tiers that work entirely through conversation. The hooks that track file activity are an enhancement on top of that, not a requirement.
It is recommended that you just ask your agent to do the whole thing, but there are manual instructions below if you would rather not do it that way.
Paste this into a new session:
Install engram:
1. Install the binary using whichever method fits:
Homebrew (Mac/Linux, no Go required):
brew tap shiblon/engram && brew install engram
Go install:
go install github.com/shiblon/engram/cmd/engram@latest
Find the full path: go env GOBIN (binary at $GOBIN/engram)
Pre-built binary:
Download from https://github.com/shiblon/engram/releases/latest,
extract, and place engram somewhere in your PATH.
Verify: engram --help (or <full-path>/engram --help if not yet in PATH)
2. Run one of:
<full-path>/engram bootstrap claude -g # Claude Code (personal machine)
<full-path>/engram bootstrap claude # Claude Code (project only)
<full-path>/engram bootstrap gemini # Gemini CLI
<full-path>/engram bootstrap antigravity # AntiGravity
<full-path>/engram bootstrap copilot # GitHub Copilot (run in project dir)
<full-path>/engram bootstrap cursor # Cursor (run in project dir)
<full-path>/engram bootstrap codex # Codex CLI (run in project dir)
<full-path>/engram bootstrap codex -g # Codex CLI (global, ~/.codex/AGENTS.md)
<full-path>/engram bootstrap codex -g --no-session-hook
# Codex fallback-only startup, keeps file tracking
<full-path>/engram bootstrap initfile <path> # any agent with a markdown init file
Open a new session when done -- the short-term stack will guide you from there.
# Homebrew (Mac/Linux, recommended):
brew tap shiblon/engram && brew install engram
# Or with Go:
go install github.com/shiblon/engram/cmd/engram@latest
# Or download a pre-built binary from https://github.com/shiblon/engram/releases/latest
engram bootstrap claude -g # or without -g for project-only hooksBootstrap writes workflow instructions into global memory, sets up session-start injection, and queues a personality setup todo for your first session. On hook-capable platforms it also adds file tracking hooks. Open a new session when done and your agent will know what to do.
Export memory to markdown so it can live in version control:
engram mem --global dump # global identity + preferences -> ~/.claude/memory/*.md
engram mem dump --tier long # settled project memory -> context/long.mdUse --tier long for the project export: long-term is the "wiki of settled
knowledge" worth committing, whereas the short-term stack is transient working
state you don't want in version control. engram mem load re-imports these
markdown files (per scope) on another checkout.
To carry all machine-local engram state — global memory, every registered project's memory, agent tools, and any pending transfers — in one archive:
engram save -o engram.tgz # on the old machine
engram restore engram.tgz # on the new machinerestore installs the global memory if the new machine has none, then stages
each project snapshot. Your agent surfaces the staged projects, and you place
each into its working tree with engram restore --apply <identity> (run from
inside that project). Projects are tracked in a manifest — engram register --list shows it, and a project is registered automatically the first time its
database is created.
Once engram is running, you mostly just talk to your agent. Here are some patterns worth trying.
Remembering things
You: remember that we're using modernc.org/sqlite to avoid CGo
Agent: stored in project long-term memory: sqlite-rationale
You: remember that for all my projects
Agent: stored in global preference memory: sqlite-cgo-preference
The agent will always tell you where it put something. If you want a specific tier:
"remember this as short-term" / "add this to the backlog" / "make this a global preference"
The conversation stack
When you need to take a detour:
You: hold on, I want to think through the API design before we continue
Agent: current context saved to short-term memory. what's on your mind?
[...design discussion...]
You: ok, let's go back to what we were doing
Agent: [reads short-term memory] we were in the middle of the auth refactor,
specifically the session token validation. picking up there.
Checking memory
You: what's in my short-term stack?
You: what are my code preferences?
You: what have we decided about this project?
You: are you bootstrapped? (checks for codename + personality)
Pruning and moving
You: that auth task is done, remove it from the backlog
You: actually, move that note to long-term — it turned into a real decision
You: clear the short-term stack, we're starting fresh
Seeing what's available
You: what can you do with memory?
Your agent will describe the tier system, what each tier is for, and how to use it — because that's stored as context it receives at every session start.