Getting started

Engram installs in a couple of minutes. There are two ways in: the command line (works everywhere) and the Claude Code plugin (which wraps the command line for you). Start with the CLI — the plugin drives it under the hood, so having it installed makes everything else smoother.

What you need

Python 3.11 or newer
git

Both of these are optional but nice to have:

gitleaks — a secret-scanning tool, if you want the built-in guard that stops credentials from ever being pushed.
An LLM API key — only for the optional session-distillation features. Engram runs fully without one; nothing core depends on it.

Install the engine (all platforms)

The install is the same three commands on Linux, macOS, and Windows. The only thing that differs is which shell you run them in.

git clone https://github.com/ad-astra26/engram && cd engram
pip install -e .          # puts `engram` on your PATH
engram init               # create + harden the store, write config, self-test

Linux

Run the commands above in your normal terminal. If pip maps to Python 2 on your system, use pip3 / python3 -m pip instead.

macOS

Identical to Linux. If you do not already have Python 3.11+, install it (for example via the official installer from python.org, or your package manager of choice), then run the three commands in Terminal.

Windows

Use PowerShell. The commands are the same; if pip is not recognized, use python -m pip install -e .. Make sure the Python you installed is on your PATH (the official installer offers a checkbox for this).

What `engram init` does

init is a one-shot setup that also checks its own work. It:

creates your store and locks it down to owner-only permissions,
writes a default config file,
and runs a self-test — building the index, verifying the integrity chain, and confirming the permissions are right.

A healthy install ends with:

✅ engram is ready.

If anything is wrong, it fails loudly and tells you what to fix — a broken install never pretends to be fine. init also prints the remaining opt-in steps (like wiring the automatic session hooks).

Where does the store live? By default, in ~/.engram/store (or wherever you point the ENGRAM_STORE environment variable). It is owner-only and never pushed anywhere.

Your first recall

Rebuild the index and ask your first question:

engram reindex                       # build the catalog over your pages
engram ask "how does X work"         # ask in plain language; get cited pages back

First runs look quiet — that's expected. A fresh store is empty, so there is nothing to surface for a session or two. It fills as you work. You do not need to seed it by hand.

You can also check the health of your store any time:

engram lint                          # find broken links, orphan pages, stale claims

Wire it into Claude Code (two steps)

The Claude Code plugin is a thin wrapper: it drives the same engram command-line tool you just installed. So there are two steps.

1. Add and install the plugin — inside Claude Code:

/plugin marketplace add ad-astra26/engram
/plugin install engram

2. Make it operational — in a normal terminal. The bootstrap script checks for Python 3.11+ (with your OK), installs the engine on your PATH, and runs the self-test:

# macOS / Linux
bash setup.sh
# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File setup.ps1

Then back in Claude Code, run /reload-plugins.

Until step 2 is done, Claude Code will show the Engram server as failed (a "command not found" style error). That is the expected signal that the engine is not installed yet — not a bug. It clears the moment the bootstrap finishes and you reload.

Once wired, Engram surfaces relevant pages at the start of every session and distills the conversation into a new page at the end. See Using it in your editor for other tools (Codex, Gemini, Cursor, and more), which use the same universal adapter.

Core concepts — understand what "sealed", "index-first", and "decay" really mean.
Commands — the full, friendly command reference.