Transforms LLM conversation history into structured semantic knowledge using episodic memory capture and graph-based consolidation.
Also known as devinmlowe/engram, @devinmlowe/engram
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 204
- Latest version
- 0.5.0
- Last commit
- Oct 19, 2026
- License
- MIT
What is Engram MCP?
Engram transforms LLM conversation history into structured semantic knowledge using episodic memory capture and graph-based consolidation.
Summary generated from the project's README
About Engram MCP server
Turning raw conversation history into a structured knowledge graph is what Engram enables for developers using LLM agents. It functions as a local-first cognitive memory system that captures episodic memories and consolidates them into semantic knowledge through a scheduled dream state process. This allows users to move beyond simple document retrieval and instead interact with emergent connections within their own data.
Users can integrate Engram with Claude Code, Cursor, Codex, or Hermes using the command line or as a Claude Code plugin. The system requires an LLM provider such as Ollama, OpenAI, Anthropic, or OpenRouter to perform memory extraction and consolidation. It operates via an MCP HTTP daemon or stdio transport and includes a web visualizer to explore the 3D knowledge graph. The setup process includes tools like engram setup and engram doctor to manage local services, model caches, and host registrations.
What you can do with it
- 1Retrieve specific past decisionsAsk the AI to find specific information from previous chat sessions using semantic search.
- 2Automate memory consolidationSchedule nightly background processing to transform raw chat logs into structured semantic knowledge.
- 3Visualize knowledge connectionsExplore the relationships between different pieces of learned information through a 3D graph interface.
- 4Sync existing project historyIngest conversation history from local Claude projects to build an initial knowledge base.
Written from the project's README. Every use case is checked against a quote from it.
How to install Engram MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Engram MCP in Claude Code
$ claude mcp add --env 'ENGRAM_MCP_TOKEN=<YOUR_ENGRAM_MCP_TOKEN>' engram -- npx -y @devinmlowe/engramInstall Engram MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"engram": {
"command": "npx",
"args": [
"-y",
"@devinmlowe/engram"
],
"env": {
"ENGRAM_MCP_TOKEN": "<YOUR_ENGRAM_MCP_TOKEN>"
}
}
}
}Install Engram MCP in VS Code
.vscode/mcp.json
{
"servers": {
"engram": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@devinmlowe/engram"
],
"env": {
"ENGRAM_MCP_TOKEN": "<YOUR_ENGRAM_MCP_TOKEN>"
}
}
}
}Install Engram MCP in VS Code CLI
$ code --add-mcp '{"name":"engram","type":"stdio","command":"npx","args":["-y","@devinmlowe/engram"],"env":{"ENGRAM_MCP_TOKEN":"<YOUR_ENGRAM_MCP_TOKEN>"}}'Install Engram MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"engram": {
"command": "npx",
"args": [
"-y",
"@devinmlowe/engram"
],
"env": {
"ENGRAM_MCP_TOKEN": "<YOUR_ENGRAM_MCP_TOKEN>"
}
}
}
}Install Engram MCP in Codex
$ codex mcp add engram --env 'ENGRAM_MCP_TOKEN=<YOUR_ENGRAM_MCP_TOKEN>' -- npx -y @devinmlowe/engramInstall Engram MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.engram] command = "npx" args = ["-y", "@devinmlowe/engram"] [mcp_servers.engram.env] ENGRAM_MCP_TOKEN = "<YOUR_ENGRAM_MCP_TOKEN>"
Install Engram MCP in Gemini CLI
$ gemini mcp add -s user -e 'ENGRAM_MCP_TOKEN=<YOUR_ENGRAM_MCP_TOKEN>' engram npx -- -y @devinmlowe/engramInstall Engram MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"engram": {
"command": "npx",
"args": [
"-y",
"@devinmlowe/engram"
],
"env": {
"ENGRAM_MCP_TOKEN": "<YOUR_ENGRAM_MCP_TOKEN>"
}
}
}
}Configuration
ENGRAM_MCP_TOKENSecretBearer token forwarded to the HTTP daemon when it requires one
ENGRAM_DB_PATHSQLite database path (default: <data dir>/engram.db, i.e. ~/.local/share/engram/engram.db)
ENGRAM_MCP_PORTPort of the optional engram HTTP daemon to bridge to (default 9907)
ENGRAM_MCP_STANDALONESet to 1 to never bridge: always run the full server in-process
| Name | Description | |
|---|---|---|
| ENGRAM_MCP_TOKEN | Bearer token forwarded to the HTTP daemon when it requires one | Secret |
| ENGRAM_DB_PATH | SQLite database path (default: <data dir>/engram.db, i.e. ~/.local/share/engram/engram.db) | |
| ENGRAM_MCP_PORT | Port of the optional engram HTTP daemon to bridge to (default 9907) | |
| ENGRAM_MCP_STANDALONE | Set to 1 to never bridge: always run the full server in-process |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledevinmlowe/engram is public and reachablegithub.com/devinmlowe/engram ↗Pass
- Package names this repository as its source@devinmlowe/engram names devinmlowe/engram as sourcenpmjs.com/package/@devinmlowe/engram ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @devinmlowe/engramnpmjs.com/package/@devinmlowe/engram/v/0.5.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-19github.com/devinmlowe/engram ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @devinmlowe/engramPass
- No critical advisory in the package or its dependencies197 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubEngram
An engram is the hypothetical physical trace of memory in neural tissue — the biochemical change that encodes what we've learned.
Local-first cognitive memory system that transforms raw LLM conversation history into structured, consolidated knowledge. Unlike traditional conversation search (which treats sessions as documents to retrieve), Engram mimics human memory architecture: episodic memories are captured, consolidated into semantic knowledge during "dream state" processing, and emergent connections surface through graph analysis — much like how a Zettelkasten's backlinks reveal Maps of Content that no individual note anticipated.
Designed as an MCP server for Claude Code and other LLM agents, with CLI and web visualization interfaces.
Install & first run
Prerequisites
- Node.js 22 or newer (
node --version) - macOS, Linux, or Windows for the CLI, MCP server, and web visualizer. Scheduled background consolidation ships an installer for each (launchd, systemd user timer, Task Scheduler); see the platform matrix below.
- Claude Code if you want
engram syncto ingest your conversation history from~/.claude/projects - At least one LLM provider for extraction and dream consolidation (see Configuration). Search,
remember, and the web visualizer work without one.
Quick start — three commands
npx @devinmlowe/engram preflight # is this node/platform/arch/libc covered by prebuilt native modules? (fix per OS if not)
npm install -g @devinmlowe/engram # puts `engram` on your PATH; the postinstall hook runs the same preflight
engram setup # doctor → init → sync (asked) → register every host present → install the three services → doctor --fix → one real extraction → summary
engram setup walks a bare install to running and ends by telling you which LLM tier did
the extraction (extraction smoke: tier=ollama memories=3). Every step prints what it did and
the manual command it stands for, so nothing is hidden. It installs all three services —
the MCP HTTP daemon, the nightly dream timer and the web visualizer (port 3001, loopback) — by
default (decision #62); --no-daemons or --daemons=mcp,dream narrows that, --host claude
narrows host registration, --no-sync / --sync skip or force indexing, --no-smoke skips the
extraction, --yes answers every question for scripts (the Linux loginctl enable-linger
prompt is never implied), --json prints the result. With no LLM provider configured the
dream timer is still installed and setup ends with [warn] dream timer installed but no LLM tier is reachable … naming the variables to set — exit 0; only a required doctor failure (or a
failed init) exits 1. Later, engram doctor --fix repairs whatever is red — the service env
file, a model cache inside node_modules, a missing Ollama model (asked first), a stopped MCP
daemon, an unregistered host — printing the manual equivalent of each; a second run says
nothing to fix. See CLI and docs/api-reference.md.
The same, by hand
engram mcp install claude # registers engram with Claude Code (codex | cursor | hermes | --all); restart the host
engram mcp install <host> edits the host's own config for you — ~/.claude.json
(--project: .mcp.json), ~/.codex/config.toml, ~/.cursor/mcp.json, or deploys the
Hermes plugin — atomically, with the previous content kept in <file>.bak, never touching
other servers, and re-running is a no-op. It prefers the HTTP daemon
(http://127.0.0.1:9907/mcp) when GET /health answers and falls back to stdio
(node …/dist/interfaces/cli/index.js mcp, which bridges to the daemon itself once one runs),
printing which and why; --transport http|stdio overrides, --dry-run shows the path and diff.
A daemon token is referenced as an environment variable (${ENGRAM_MCP_TOKEN} /
bearer_token_env_var / ${env:ENGRAM_MCP_TOKEN}), never written; engram mcp status reports
every host, whether it points at this install, whether its daemon answers and whether the
variable resolves. See Registering hosts below.
From source
git clone https://github.com/devinmlowe/engram.git
cd engram
node scripts/preflight.cjs # optional: the native-dependency verdict before anything is installed
npm install # runs the same preflight as postinstall, then builds via the "prepare" script
npm link # puts `engram` on your PATH (or run `node dist/interfaces/cli/index.js` directly)
Either way, continue with engram setup — or step by step:
engram preflight # prebuilt / compiled locally / unsupported per native module, with the fix for this OS
engram doctor # node, platform/arch, native modules, model cache, ollama tier, llm providers, data dir, env file, install path, mcp daemon, hosts, extraction smoke — all [ok]?
engram doctor --fix # apply the known remediations (env file, durable model cache, ollama pull with confirmation, start a stopped daemon, register a host) and re-check
engram init # creates engram.db in the data dir (default ~/.local/share/engram; see Configuration) and downloads the embedding model
engram sync # index conversations from ~/.claude/projects (optional)
engram search "what did I decide about caching"
engram mcp install --all # from a checkout: register every host present (~/.claude, ~/.codex, ~/.cursor, ~/.hermes)
scripts/install-mcp-daemon.sh install; scripts/install-daemon.sh install; scripts/install-visualizer.sh install # the three services (what setup runs)
engram doctor ends with an extraction smoke line: one real extraction over your most recent
conversation (or a bundled fixture when nothing is indexed yet) under a 60 s budget with a
capped input, reporting tier=<ollama|openai|openrouter|anthropic> memories=N or every tier's
reason when none answers. Memories it extracts from a real conversation are written like any
other, stamped source=smoke (find them with engram memories list, remove them with forget);
the fixture is never written. --no-smoke skips it; --strict exits 1 when any line is not
[ok] (CI).
First run downloads models once.
engram init(or the first search) pulls several hundred MB of model weights into~/.local/share/engram/models(or$ENGRAM_MODEL_CACHE_DIR/$HF_HOME/hub), where they survive reinstalls and upgrades; see Model cache. SetENGRAM_RERANK_ENABLED=falseto skip the reranker model.
Install as a Claude Code plugin (recommended)
No clone, no absolute paths. In Claude Code:
/plugin marketplace add devinmlowe/engram
/plugin install engram@engram
This repo is its own marketplace (.claude-plugin/marketplace.json); the plugin
(.claude-plugin/plugin.json) runs the published npm package as a stdio MCP server —
npx -y @devinmlowe/engram@<version> mcp, version pinned to the release — and adds the
/engram:recall, /engram:remember, /engram:explore-graph, /engram:reflect and
/engram:engram-connect commands (bundled from commands/; their tools are
mcp__plugin_engram_engram__<tool>). /mcp should list engram with 16 tools; the first
recall downloads the embedding model once (see the note above). The plugin updates through
the marketplace (/plugin update engram@engram after a release); engram update keeps
handling the CLI, daemons and the Hermes plugin.
The very first start is slow. The first
npxrun installs the package and its prebuilt native modules into the npm cache — once per pinned version, then it is a cache hit. If Claude Code reports the server timed out during that install, raise its startup timeout (milliseconds):MCP_TIMEOUT=120000 claude. Two warm paths:npm install -g @devinmlowe/engramfirst, so the package (andengram doctor/engram init) is already on the machine; or run the HTTP daemon (scripts/install-mcp-daemon.sh install, below) —engram mcpthen bridges to it and the host process never opens the database or loads the model (see Transports).
Registering hosts (engram mcp install)
engram mcp install claude # ~/.claude.json (--project: ./.mcp.json)
engram mcp install codex # ~/.codex/config.toml (--project: ./.codex/config.toml)
engram mcp install cursor # ~/.cursor/mcp.json (--project: ./.cursor/mcp.json)
engram mcp install hermes # deploys interfaces/hermes-plugin to ~/.hermes (+ profiles that already have it)
engram mcp install --all --dry-run # every host whose config dir exists; print path + unified diff, write nothing
engram mcp status # registered? this install? daemon answering? ENGRAM_MCP_TOKEN resolving?
engram mcp uninstall codex # removes only the engram entry; <file>.bak keeps the previous content
Decisions: HTTP when the daemon answers /health, else stdio (#51); the token is referenced by
environment variable and never written unless you pass --inline-token (#52). With the Claude
Code plugin installed, mcp install claude skips the user-scope entry (it would register the
server twice) unless --force; mcp status lists the plugin as a registered Claude host. A
GUI-launched host does not inherit a fish/zsh login shell, so when the daemon requires a token
mcp status prints the platform fix (launchctl setenv ENGRAM_MCP_TOKEN … on macOS,
~/.config/environment.d/ on Linux, setx on Windows). No host process is restarted, and the
command needs no network beyond the loopback probe.
Manual configuration (if you would rather edit the file yourself)
Add the server to your Claude Code MCP config (~/.claude.json, or a project-level .mcp.json).
From npm:
{
"mcpServers": {
"engram": { "command": "npx", "args": ["-y", "@devinmlowe/engram", "mcp"] }
}
}
or, for a source checkout, point at the compiled server with an absolute path:
{
"mcpServers": {
"engram": {
"command": "node",
"args": ["/absolute/path/to/engram/dist/interfaces/mcp/server.js"],
"env": {}
}
}
}
The .mcp.json shipped in this repo does the same thing with a repo-relative path and is picked
up automatically when you open the engram checkout itself in Claude Code (it is for developing
engram; the plugin does not use it).
Optional: background consolidation and visualization
./scripts/install-mcp-daemon.sh install # MCP HTTP daemon on 127.0.0.1:9907 via launchd (what the Hermes plugin talks to)
./scripts/install-daemon.sh install # nightly `engram dream` at 02:00 via launchd
./scripts/install-visualizer.sh install # macOS launchd visualizer
On Linux the same scripts detect uname -s and install systemd user units instead
(no root; loginctl enable-linger $USER if you want them to run while logged out):
./scripts/install-mcp-daemon.sh install # renders systemd/engram-mcp.service, enables it (Restart=always)
./scripts/install-mcp-daemon.sh status # unit state, GET /health, effective data dir, last log lines
./scripts/install-daemon.sh install # renders systemd/engram-dream.{service,timer}, enables engram-dream.timer
./scripts/install-daemon.sh status # systemctl --user list-timers + last log lines
./scripts/install-daemon.sh run-now # systemctl --user start engram-dream.service
macOS/Linux: MCP HTTP daemon lifecycle
scripts/install-mcp-daemon.sh has the same six verbs as its Windows sibling
(install, uninstall, start, stop, restart, status). It renders
launchd/com.engram.mcp.plist (macOS) or systemd/engram-mcp.service (Linux)
from the checkout it runs in, builds dist/, and waits for GET /health before
reporting success. The service runs scripts/run-mcp-daemon.sh, which sources
~/.config/engram/env (created on install, mode 600) so ENGRAM_DATA_DIR,
ENGRAM_MODEL_CACHE_DIR, ENGRAM_HTTP_WORKERS and ENGRAM_MCP_PORT can change
without re-rendering anything. The data directory the installer resolved is
also rendered into the service, so the daemon and the CLI never open different
databases; status prints it and warns when a second engram.db exists at the
legacy path. install stops an unsupervised process holding the port and
retires a hand-written ai.hermes.engram-mcp LaunchAgent from the 0.1.x docs
(the file is renamed *.retired-by-engram, not deleted). engram doctor
reports the same /health probe as its mcp daemon check.
On Windows, use the built-in per-user Task Scheduler adapters:
.\scripts\install-daemon.ps1 install -PersistEnv # daily 02:00 task running the compiled CLI with the resolved node.exe
.\scripts\install-daemon.ps1 status
.\scripts\install-visualizer.ps1 install
.\scripts\install-visualizer.ps1 status
.\scripts\install-mcp-daemon.ps1 install # per-user Task Scheduler task for the MCP HTTP daemon (loopback only)
.\scripts\install-mcp-daemon.ps1 status
Windows: MCP HTTP daemon lifecycle
scripts/install-mcp-daemon.ps1 registers a per-user Task Scheduler task,
\Engram\MCP, that starts at logon and runs scripts/run-mcp-daemon.ps1 with
absolute paths to node.exe and the compiled dist\interfaces\mcp\server.js.
The server binds 127.0.0.1:9907 by design — it has no authentication and
never binds any other address, so the task never exposes the MCP port to the
network.
Six verbs, same shape as the other installers: install, uninstall,
start, stop, restart, status. status reports both the Task
Scheduler state and a live GET /health check against the daemon.
Process hygiene: the runner writes its own pid and the child node.exe pid
to files under the data directory; stop and uninstall tree-kill those
pids with taskkill.exe and then sweep for any leftover node.exe or
run-mcp-daemon.ps1 process by command line, so a stale or missing pid file
can never leave an orphan process behind.
Restart-on-failure is bounded at two levels: the runner gives up and exits 1 after 5 restarts within a 600-second window, and Task Scheduler itself retries a failed task 3 times at 1-minute intervals before stopping — so a broken install cannot restart-loop forever. A clean server exit (code 0) is treated as a deliberate stop and is not restarted. The task inherits your user-scope environment variables (API keys included); nothing is copied into the task definition or committed to the repo.
Reboot smoke-test procedure (copy-paste each block in order):
- Install and confirm it's healthy:
.\scripts\install-mcp-daemon.ps1 install .\scripts\install-mcp-daemon.ps1 status # taskState Running, healthy True - Restart Windows and log back in — do not start anything by hand.
- Confirm the task came back on its own:
.\scripts\install-mcp-daemon.ps1 status # taskState Running, healthy True curl.exe http://127.0.0.1:9907/health # { "status": "ok", ... } - Confirm the MCP handshake works — initialize, then the
initializednotification, thentools/list, threading theMcp-Session-Idresponse header through each call:curl.exe -s -D headers.txt -o init.json http://127.0.0.1:9907/mcp ` -H "Content-Type: application/json" ` -H "Accept: application/json, text/event-stream" ` -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0"}}}' $sid = (Select-String -Path headers.txt -Pattern '^Mcp-Session-Id:\s*(\S+)').Matches.Groups[1].Value curl.exe -s http://127.0.0.1:9907/mcp ` -H "Content-Type: application/json" ` -H "Accept: application/json, text/event-stream" ` -H "Mcp-Session-Id: $sid" ` -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' curl.exe -s http://127.0.0.1:9907/mcp ` -H "Content-Type: application/json" ` -H "Accept: application/json, text/event-stream" ` -H "Mcp-Session-Id: $sid" ` -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' - Confirm Codex/Claude Code can
recallandrememberthrough this same server without you starting Node by hand. - Stop it and confirm no MCP process survives:
.\scripts\install-mcp-daemon.ps1 stop Get-CimInstance Win32_Process -Filter "Name = 'node.exe'" | Where-Object CommandLine -like '*mcp\server.js*' # empty - Uninstall and confirm only the visualizer task remains:
.\scripts\install-mcp-daemon.ps1 uninstall Get-ScheduledTask -TaskPath '\Engram\' # lists Visualizer, not MCP
All visualizer paths run the same compiled Node server on loopback at http://127.0.0.1:3001
and write logs under the engram data directory; all dream paths run
node dist/interfaces/cli/index.js dream and log to <data dir>/logs/dream.log.
The installers render launchd/*.plist (macOS) or systemd/engram-{mcp,dream}.service (Linux)
from the checkout you run them in, whatever its
location, and use whichever node they find (fnm, Homebrew, nvm, or system). The dream daemon
takes its API keys from ~/.config/engram/env (mode 600, created by the installer with a
commented template; $XDG_CONFIG_HOME is honoured) — the plist itself never contains secrets.
If you installed before that file existed, move the keys there and re-run install; see
scripts/README.md for the steps.
Every script checks its external tools up front and names what to install. The visualizer
installer probes its port with node (or curl against /api/health), using lsof only as
an optional fast path when it is installed; the Claude Code post-compaction hook
(scripts/compact-dream.sh) and the Hermes heartbeat digest (scripts/commitments-surface.sh)
need only node; the hook honours ENGRAM_DATA_DIR / ENGRAM_LOGS_DIR. No script needs jq
or python3.
Supported platforms
| Component | macOS | Linux | Windows |
|---|---|---|---|
CLI (engram init/sync/search/dream) |
yes | yes | yes |
| MCP server (stdio + HTTP) | yes | yes | yes |
Web visualizer (node dist/interfaces/web/server.js) |
yes | yes | yes |
| Visualizer keep-alive service | launchd (scripts/install-visualizer.sh) |
run under your own supervisor (systemd user unit, pm2) | Task Scheduler (scripts/install-visualizer.ps1) |
| Nightly dream daemon | launchd (scripts/install-daemon.sh) |
systemd user timer engram-dream.timer (scripts/install-daemon.sh) |
Task Scheduler (scripts/install-daemon.ps1) |
MCP HTTP daemon keep-alive (--http --port 9907) |
run under your own supervisor (launchd agent, KeepAlive) | run under your own supervisor (systemd user unit) | Task Scheduler (scripts/install-mcp-daemon.ps1) |
Claude Code hooks (scripts/*.sh) |
yes | yes (bash, node) | WSL or Git Bash only |
Supported platform/arch set
Engram depends on three native/prebuilt chains: better-sqlite3, sqlite-vec (alpha; ships
platform packages only), and onnxruntime-node (pulled in by @xenova/transformers). Engram
works where all three have prebuilt binaries for your process.platform, process.arch and libc
(glibc vs musl on Linux); since better-sqlite3 13 every chain is N-API, so the Node major no
longer matters as long as it is ≥ 22.
The table is generated from scripts/preflight.cjs, the same table the preflight and engram doctor consult, and a test fails when the two drift:
| Target | Machines | better-sqlite3 | sqlite-vec | onnxruntime-node | Engram |
|---|---|---|---|---|---|
darwin-arm64 |
Apple silicon Macs | prebuilt | prebuilt | prebuilt | supported (CI: macos-latest) |
darwin-x64 |
Intel Macs | prebuilt | prebuilt | prebuilt | supported |
linux-arm64 |
64-bit ARM Linux (glibc): Graviton, Raspberry Pi OS 64-bit, Apple-silicon VMs | prebuilt | prebuilt | prebuilt | supported (CI: ubuntu-24.04-arm) |
linux-x64 |
x86-64 Linux (glibc: Debian, Ubuntu, Fedora, …) | prebuilt | prebuilt | prebuilt | supported (CI: ubuntu-latest) |
linuxmusl-arm64 |
64-bit ARM Alpine / musl | prebuilt | — | — | not supported |
linuxmusl-x64 |
x86-64 Alpine / musl (node:*-alpine images) |
prebuilt | — | — | not supported (CI: node:22-alpine container asserts this verdict) |
win32-arm64 |
Windows on ARM (Snapdragon, Apple-silicon VMs running Windows 11 ARM) | prebuilt | — | prebuilt | not supported (CI: windows-11-arm asserts this verdict) |
win32-x64 |
x86-64 Windows 10/11 | prebuilt | prebuilt | prebuilt | supported (CI: windows-latest, experimental) |
| any other target | FreeBSD, 32-bit x86, … | compiles | — | — | not supported |
Every native dependency (better-sqlite3, sqlite-vec, onnxruntime-node) is N-API / Node-version independent: the same binaries serve every Node major ≥ 22, odd (non-LTS) majors included. Generated from scripts/preflight.cjs by node scripts/supported-platforms.cjs --write; --check runs in the test suite.
Three things tell you where you stand:
npx @devinmlowe/engram preflight(orengram preflightonce installed,node scripts/preflight.cjsin a checkout) prints one line per native module —[ok] prebuilt,[warn] compiled locally/will compile (needs python3 + C++ toolchain),[FAIL] unsupported,[--] unknown (<reason>)— followed by the exact fix for your OS (xcode-select --install,sudo apt install build-essential python3,sudo dnf install gcc-c++ make python3,apk add build-base python3, Visual Studio Build Tools with the "Desktop development with C++" workload). The verdict comes from the static target table (every native module is N-API, so the Node major never matters); after an install it also confirms the shipped binary is really innode_modules(abuild/Release/better_sqlite3.nodein place of the bundledprebuilds/<target>.nodemeans node-gyp compiled it locally).--jsonprints the structured result;--strictexits 1 on any[FAIL];--expect prebuilt(or--expect better-sqlite3=prebuilt,sqlite-vec=unsupported) exits 1 unless the verdicts match, which is how CI fails a dependency bump that drops a prebuild.npm_config_platform/npm_config_arch/npm_config_target_arch/npm_config_libcoverride the target.npm installruns that preflight as a non-fatal postinstall hook (ENGRAM_SKIP_PREFLIGHT=1silences it). It never fails the install:package.jsondeliberately declares no hardos/cpufields, which would refuse to install for anyone with a working toolchain on an unlisted target.engram doctorruns the full post-build checks; itsbetter-sqlite3andsqlite-veclines end withprebuilt — …orcompiled locally — …, which tells an upgrade that silently fell back to node-gyp apart from one that used the prebuild (an offline or proxied install, ornpm_config_build_from_source, is the usual cause).
Caveats: Windows on ARM, armv7 and Alpine/musl. sqlite-vec publishes no binary for
win32-arm64 or linux-arm (armv7), and its Linux builds — like onnxruntime-node's — are
glibc-only (they need ld-linux and do not load on musl even with gcompat). better-sqlite3
itself ships prebuilds for win32-arm64 and musl (13.x dropped its 32-bit linux-arm ones, so
armv7 compiles it from source), so npm install succeeds there and `engra
Engram MCP questions
How do I add Engram MCP to Claude Code?
Run claude mcp add --env 'ENGRAM_MCP_TOKEN=<YOUR_ENGRAM_MCP_TOKEN>' engram -- npx -y @devinmlowe/engram in your terminal. Add --scope user to make it available in every project.
How do I add Engram MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What is Engram?
Engram is a local-first cognitive memory system that transforms raw LLM conversation history into structured, consolidated knowledge using episodic and semantic memory architectures.
How do I install Engram for Claude Code?
You can install it as a plugin directly in Claude Code using the commands /plugin marketplace add devinmlowe/engram and /plugin install engram@engram.
Does Engram require an LLM provider?
Search, remember, and the web visualizer work without an LLM, but at least one provider is needed for extraction and dream consolidation.