engram

# Engram

[![CI](https://github.com/devinmlowe/engram/actions/workflows/ci.yml/badge.svg)](https://github.com/devinmlowe/engram/actions/workflows/ci.yml)

> *An engram is the hypothetical physical trace of memory in neural tissue — the biochemical change that encodes what we've learned.*

<p align="center">
  <img src="assets/galaxy-view.webp" alt="Engram Galaxy View — 3D knowledge graph visualization" width="100%">
</p>

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](https://docs.anthropic.com/en/docs/claude-code) if you want `engram sync` to ingest your conversation history from `~/.claude/projects`
- At least one LLM provider for extraction and dream consolidation (see [Configuration](#configuration)). Search, `remember`, and the web visualizer work without one.

**Quick start — three commands**

```bash
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](#cli) and `docs/api-reference.md`.

**The same, by hand**

```bash
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](#registering-hosts-engram-mcp-install) below.

**From source**

```bash
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:

```bash
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](#model-cache).
> Set `ENGRAM_RERANK_ENABLED=false` to 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 `npx` run 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/engram` first, so the
> package (and `engram doctor`/`engram init`) is already on the machine; or run the HTTP daemon
> (`scripts/install-mcp-daemon.sh install`, below) — `engram mcp` then bridges to it and the host
> process never opens the database or loads the model (see [Transports](#transports-stdio-default-and-http)).

**Registering hosts (`engram mcp install`)**

```bash
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 t