Engram

Engram

エングラムとは、神経組織における記憶の仮説上の物理的痕跡、つまり学習した内容を符号化する生化学的変化です。

ローカルファーストの認知記憶システムです。LLM の生の会話履歴を、構造化され統合された知識へと変換します。セッションを検索対象のドキュメントとして扱う従来の会話検索とは異なり、Engram は人間の記憶構造を模倣します。エピソード記憶を記録し、「夢状態」の処理中に意味知識へと統合し、グラフ分析を通じて創発的なつながりを浮かび上がらせます。これは、Zettelkasten のバックリンクから、個々のノートが予期していなかったコンテンツマップが明らかになる様子に似ています。

Claude Code やその他の LLM エージェント向けの MCP サーバーとして設計されており、CLI とウェブ可視化インターフェースも備えています。

インストールと初回起動

前提条件

• Node.js 22 以降（node --version）
• CLI、MCP サーバー、ウェブビジュアライザーは macOS、Linux、Windows に対応しています。スケジュールされたバックグラウンド統合には各プラットフォーム用のインストーラーが付属します（launchd、systemd ユーザータイマー、タスクスケジューラ）。下記のプラットフォーム一覧を参照してください。
• engram sync で ~/.claude/projects から会話履歴を取り込む場合は、Claude Code
• 抽出と夢の統合に、LLM プロバイダーが少なくとも 1 つ必要です（設定を参照）。検索、remember、ウェブビジュアライザーは、LLM プロバイダーなしで動作します。

クイックスタート — 3 つのコマンド

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 は、何もない状態から稼働状態までセットアップを進め、抽出に使用した LLM のティアを最後に表示します（extraction smoke: tier=ollama memories=3）。各ステップでは、実行した内容と、それに相当する手動コマンドが表示されるため、処理が隠れることはありません。デフォルトでは3 つすべてのサービス、つまり MCP HTTP デーモン、夜間の夢タイマー、ウェブビジュアライザー（ポート 3001、ループバック）をインストールします（決定 #62）。--no-daemons または --daemons=mcp,dream で対象を絞り、--host claude でホスト登録の対象を絞れます。--no-sync / --sync でインデックス作成をスキップまたは強制し、--no-smoke で抽出をスキップできます。スクリプトで全ての質問に回答するには --yes を指定します（Linux の loginctl enable-linger の確認は自動的に省略されません）。--json を指定すると結果を出力します。LLM プロバイダーが設定されていない場合も夢タイマーはインストールされ、設定すべき変数を示す [warn] dream timer installed but no LLM tier is reachable … を表示してセットアップは終了します。終了コードは 0 です。必須の doctor チェックに失敗した場合（または init に失敗した場合）のみ、終了コード 1 になります。その後は engram doctor --fix で、赤く表示された項目（サービスの環境変数ファイル、node_modules 内のモデルキャッシュ、不足している Ollama モデル（先に確認します）、停止中の MCP デーモン、未登録のホスト）を修復できます。各項目について手動で行う場合の方法も表示され、2 回目の実行では nothing to fix と表示されます。CLI と docs/api-reference.md を参照してください。

手動で同じ設定を行う場合

engram mcp install claude           # registers engram with Claude Code (codex | cursor | hermes | --all); restart the host

engram mcp install <host> は、ホスト自身の設定を編集します。~/.claude.json（--project の場合は .mcp.json）、~/.codex/config.toml、~/.cursor/mcp.json を更新するか、Hermes プラグインをデプロイします。処理はアトミックに行われ、以前の内容は <file>.bak に保持されます。他のサーバーには触れず、再実行しても何も変更されません。GET /health に応答がある場合は HTTP デーモン（http://127.0.0.1:9907/mcp）を優先し、そうでない場合は stdio（node …/dist/interfaces/cli/index.js mcp。デーモンが起動していれば、そこへ接続します）にフォールバックします。どちらを選んだかとその理由も表示します。--transport http|stdio で指定を上書きでき、--dry-run ではパスと差分を表示します。デーモントークンは環境変数（${ENGRAM_MCP_TOKEN} / bearer_token_env_var / ${env:ENGRAM_MCP_TOKEN}）として参照され、書き込まれることはありません。engram mcp status では、すべてのホストについて、このインストールを参照しているか、デーモンが応答しているか、環境変数が解決されるかを確認できます。下記のホストの登録（engram mcp install）を参照してください。 ソースから

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)

どちらの場合も、engram setup を続けて実行してください。手順を分けて進めることもできます。

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 の最後には extraction smoke 行が表示されます。この行では、直近の会話（まだ何もインデックスされていない場合は、同梱のフィクスチャ）を使って、入力を上限までに制限し、60 秒の制限時間内で実際に抽出を 1 回行います。回答した場合は tier=<ollama|openai|openrouter|anthropic> memories=N と表示し、どのティアも回答しない場合はすべてのティアの理由を表示します。実際の会話から抽出したメモリーは、ほかのメモリーと同様に保存され、source=smoke の印が付きます（engram memories list で見つけて、forget で削除できます）。フィクスチャが保存されることはありません。--no-smoke を指定するとスキップされます。--strict を指定すると、いずれかの行が [ok] でない場合に終了コード 1 で終了します（CI）。

初回実行時にモデルがダウンロードされます。 engram init（または最初の検索）で、数百 MB のモデルウェイトが ~/.local/share/engram/models（または $ENGRAM_MODEL_CACHE_DIR／$HF_HOME/hub）にダウンロードされます。再インストールやアップグレード後も保持されます。詳しくはモデルキャッシュをご覧ください。リランカーモデルをスキップするには、ENGRAM_RERANK_ENABLED=false を設定してください。

Claude Code プラグインとしてインストールする（推奨）

クローンも絶対パスも不要です。Claude Code で次を実行します。

/plugin marketplace add devinmlowe/engram
/plugin install engram@engram

このリポジトリ自体がマーケットプレイス（.claude-plugin/marketplace.json）です。プラグイン（.claude-plugin/plugin.json）は、公開済みの npm パッケージを stdio MCP サーバーとして実行します。実行コマンドは npx -y @devinmlowe/engram@<version> mcp で、バージョンはリリースに固定されています。また、/engram:recall、/engram:remember、/engram:explore-graph、/engram:reflect、/engram:engram-connect コマンドも追加されます（commands/ から同梱。対応するツールは mcp__plugin_engram_engram__<tool> です）。/mcp には 16 個のツールを持つ engram が表示されるはずです。最初の recall で埋め込みモデルが一度ダウンロードされます（上記の注を参照）。プラグインはマーケットプレイス経由で更新されます（リリース後に /plugin update engram@engram を実行）。CLI、デーモン、Hermes プラグインの更新は、引き続き engram update で行います。

最初の起動には時間がかかります。 最初の npx の実行時に、パッケージとビルド済みのネイティブモジュールが npm キャッシュにインストールされます。これは固定されたバージョンごとに一度だけで、以降はキャッシュが使われます。このインストール中にサーバーがタイムアウトしたと Claude Code に報告された場合は、起動タイムアウトをミリ秒単位で延長してください。例：MCP_TIMEOUT=120000 claude。事前に npm install -g @devinmlowe/engram を実行しておけば、パッケージ（および engram doctor／engram init）がすでにマシンにインストールされた状態になります。または、HTTP デーモンを実行してください（下記の scripts/install-mcp-daemon.sh install）。その場合、engram mcp はデーモンへのブリッジとして動作し、ホストプロセスがデータベースを開いたりモデルを読み込んだりすることはありません（トランスポートを参照）。

ホストの登録（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

判断基準：デーモンの /health が応答する場合は HTTP、そうでない場合は stdio（#51）です。トークンは環境変数で参照され、--inline-token を指定しない限り書き込まれません（#52）。Claude Code プラグインがインストール済みの場合、mcp install claude はユーザースコープのエントリをスキップします（サーバーが二重に登録されるため）。--force を指定すれば登録できます。mcp status では、登録済みの Claude ホストとしてプラグインが表示されます。GUI から起動されたホストは fish／zsh のログインシェルを継承しません。そのため、デーモンにトークンが必要な場合、mcp status はプラットフォームごとの設定方法を表示します（macOS では launchctl setenv ENGRAM_MCP_TOKEN …、Linux では ~/.config/environment.d/、Windows では setx）。ホストプロセスは再起動されず、このコマンドでループバックの確認以外のネットワーク接続が必要になることもありません。

手動設定（自分でファイルを編集する場合）

サーバーを Claude Code の MCP 設定（~/.claude.json またはプロジェクトレベルの .mcp.json）に追加します。npm を使う場合：

{
  "mcpServers": {
    "engram": { "command": "npx", "args": ["-y", "@devinmlowe/engram", "mcp"] }
  }
}

または、ソースをチェックアウトしている場合は、コンパイル済みサーバーを絶対パスで指定します。

{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["/absolute/path/to/engram/dist/interfaces/mcp/server.js"],
      "env": {}
    }
  }
}

このリポジトリに同梱されている .mcp.json も同じ設定を、リポジトリ相対パスで行います。Claude Code で engram 自体のチェックアウトを開くと自動的に読み込まれます（これは engram の開発用であり、プラグインでは使用されません）。

オプション：バックグラウンドでの統合と可視化

./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

Linux では、同じスクリプトが uname -s を検出し、代わりに systemd の ユーザー ユニットをインストールします （root 権限は不要です。ログアウト中も実行する場合は loginctl enable-linger $USER を実行してください）。

./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 デーモンのライフサイクル

scripts/install-mcp-daemon.sh には、Windows 版と同じ 6 つの動詞（install、uninstall、start、stop、restart、status）があります。実行元のチェックアウトから launchd/com.engram.mcp.plist（macOS）または systemd/engram-mcp.service（Linux）を生成し、 dist/ をビルドして、成功を報告する前に GET /health を待ちます。このサービスは scripts/run-mcp-daemon.sh を実行します。このスクリプトは ~/.config/engram/env（install 時に作成され、モードは 600）を読み込むため、ENGRAM_DATA_DIR、 ENGRAM_MODEL_CACHE_DIR、ENGRAM_HTTP_WORKERS、ENGRAM_MCP_PORT は、 サービス設定を再生成せずに変更できます。インストーラーが解決したデータディレクトリも サービス設定に反映されるため、デーモンと CLI が異なるデータベースを開くことはありません。 status はこのパスを表示し、レガシーパスに 2 つ目の engram.db が存在する場合は警告します。install は、ポートを使用している監視対象外のプロセスを停止し、 0.1.x のドキュメントに記載されていた手書きの ai.hermes.engram-mcp LaunchAgent を無効化します（ファイルは削除されず、*.retired-by-engram に名前が変更されます）。engram doctor は、mcp daemon のチェックとして同じ /health プローブの結果を報告します。

Windows では、組み込みのユーザーごとのタスク スケジューラ アダプターを使用します。

.\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 デーモンのライフサイクル

scripts/install-mcp-daemon.ps1 は、ログオン時に起動し、 scripts/run-mcp-daemon.ps1 を node.exe とコンパイル済みの dist\interfaces\mcp\server.js への絶対パスを指定して実行する、ユーザーごとのタスク スケジューラ タスク \Engram\MCP を登録します。サーバーは設計上 127.0.0.1:9907 にバインドします。認証機能はなく、 他のアドレスにバインドすることもないため、このタスクによって MCP ポートがネットワークに公開されることはありません。

他のインストーラーと同じ形式で、6 つの動詞を使用します：install、uninstall、 start、stop、restart、status。status はタスク スケジューラの状態と、デーモンに対するライブの GET /health チェックの両方を報告します。

プロセスの管理：ランナーは自身の PID と子プロセスである node.exe の PID をデータディレクトリ内のファイルに書き込みます。stop と uninstall は taskkill.exe でこれらの PID のプロセスツリーを強制終了し、その後コマンドラインを使って残っている node.exe または run-mcp-daemon.ps1 プロセスを検索して終了します。そのため、PID ファイルが古くなっていたり見つからなかったりしても、孤立プロセスが残ることはありません。

再起動時の失敗処理には、2 段階の上限があります。ランナーは 600 秒の間に 5 回再起動すると諦めて終了コード 1 で終了し、タスク スケジューラ自体は失敗したタスクを 1 分間隔で 3 回再試行してから停止します。そのため、インストールに問題があっても再起動ループが無限に続くことはありません。サーバーが正常に終了した場合（コード 0）は意図的な停止として扱われ、再起動されません。このタスクはユーザースコープの環境変数（API キーを含む）を引き継ぎます。タスク定義に値がコピーされたり、リポジトリにコミットされたりすることはありません。

再起動後のスモークテスト手順（各ブロックを順番にコピーして実行してください）：

1. インストールし、正常に動作していることを確認します：

   .\scripts\install-mcp-daemon.ps1 install
   .\scripts\install-mcp-daemon.ps1 status   # taskState Running, healthy True
   

2. Windows を再起動して再度ログインします。手動で何も起動しないでください。
3. タスクが自動的に再開したことを確認します：

   .\scripts\install-mcp-daemon.ps1 status   # taskState Running, healthy True
   curl.exe http://127.0.0.1:9907/health     # { "status": "ok", ... }
   

4. MCP ハンドシェイクが機能することを確認します。まず initialize、次に initialized 通知、その後 tools/list を実行し、各呼び出しで Mcp-Session-Id レスポンス ヘッダーを引き継ぎます：

   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"}'
   

5. Node を手動で起動しなくても、Codex/Claude Code が同じサーバー経由で recall と remember を実行できることを確認します。
6. 停止し、MCP プロセスが残っていないことを確認します：

   .\scripts\install-mcp-daemon.ps1 stop
   Get-CimInstance Win32_Process -Filter "Name = 'node.exe'" | Where-Object CommandLine -like '*mcp\server.js*'   # empty
   

7. アンインストールし、ビジュアライザーのタスクだけが残っていることを確認します：

   .\scripts\install-mcp-daemon.ps1 uninstall
   Get-ScheduledTask -TaskPath '\Engram\'   # lists Visualizer, not MCP
   

すべてのビジュアライザーのパスでは、ループバック上の http://127.0.0.1:3001 で同じコンパイル済み Node サーバーを実行し、engram データディレクトリにログを書き込みます。すべての dream パスでは node dist/interfaces/cli/index.js dream を実行し、<data dir>/logs/dream.log にログを記録します。 インストーラーは、実行時にいるチェックアウトから launchd/*.plist（macOS）または systemd/engram-{mcp,dream}.service（Linux）を生成します。チェックアウトの場所は問いません。また、見つかった node（fnm、Homebrew、nvm、またはシステムのもの）を使用します。dream デーモンは API キーを ~/.config/engram/env から読み込みます（モード 600、インストーラーがコメント付きテンプレートとともに作成し、$XDG_CONFIG_HOME に対応）。plist 自体にシークレットが含まれることはありません。このファイルが作成される前にインストールした場合は、キーをそのファイルに移動して install を再実行してください。手順については、scripts/README.md を参照してください。

すべてのスクリプトは、外部ツールを最初に確認し、インストールが必要なものを明示します。ビジュアライザーのインストーラーは、node（または /api/health に対する curl）でポートを確認します。lsof がインストールされている場合のみ、高速化のためのオプションとして使用します。Claude Code の圧縮後フック（scripts/compact-dream.sh）と Hermes のハートビートダイジェスト（scripts/commitments-surface.sh）に必要なのは node だけです。フックは ENGRAM_DATA_DIR / ENGRAM_LOGS_DIR に対応しています。どのスクリプトも jq や python3 は必要ありません。

対応プラットフォーム

コンポーネント	macOS	Linux	Windows
CLI（engram init/sync/search/dream）	対応	対応	対応
MCP サーバー（stdio + HTTP）	対応	対応	対応
Web ビジュアライザー（node dist/interfaces/web/server.js）	対応	対応	対応
ビジュアライザーの常時稼働サービス	launchd（scripts/install-visualizer.sh）	独自のスーパーバイザーで実行（systemd ユーザーユニット、pm2）	タスク スケジューラ（scripts/install-visualizer.ps1）
夜間 dream デーモン	launchd（scripts/install-daemon.sh）	systemd ユーザータイマー engram-dream.timer（scripts/install-daemon.sh）	タスク スケジューラ（scripts/install-daemon.ps1）
MCP HTTP デーモンの常時稼働（--http --port 9907）	独自のスーパーバイザーで実行（launchd エージェント、KeepAlive）	独自のスーパーバイザーで実行（systemd ユーザーユニット）	タスク スケジューラ（scripts/install-mcp-daemon.ps1）
Claude Code フック（scripts/*.sh）	対応	対応（bash、node）	WSL または Git Bash のみ

対応するプラットフォーム／アーキテクチャ

Engram は、3 つのネイティブ／事前ビルド済み依存チェーン（better-sqlite3、sqlite-vec（アルファ版。プラットフォームパッケージのみを同梱）、および @xenova/transformers が取り込む onnxruntime-node）に依存します。process.platform、process.arch、および libc（Linux の glibc または musl）に対応する事前ビルド済みバイナリが3つすべてに存在する環境で Engram を使用できます。better-sqlite3 13 以降、すべての依存チェーンは N-API のため、Node のメジャーバージョンは関係なく、≥ 22 であれば使用できます。 以下の表は scripts/preflight.cjs から生成されます。これは preflight と engram doctor が参照するものと同じ表で、両者の不一致があるとテストは失敗します。

ターゲット	マシン	better-sqlite3	sqlite-vec	onnxruntime-node	Engram
darwin-arm64	Apple シリコン搭載 Mac	事前ビルド済み	事前ビルド済み	事前ビルド済み	対応（CI：macos-latest）
darwin-x64	Intel 搭載 Mac	事前ビルド済み	事前ビルド済み	事前ビルド済み	対応
linux-arm64	64 ビット ARM Linux（glibc）：Graviton、Raspberry Pi OS 64 ビット版、Apple シリコン VM	事前ビルド済み	事前ビルド済み	事前ビルド済み	対応（CI：ubuntu-24.04-arm）
linux-x64	x86-64 Linux（glibc：Debian、Ubuntu、Fedora など）	事前ビルド済み	事前ビルド済み	事前ビルド済み	対応（CI：ubuntu-latest）
linuxmusl-arm64	64 ビット ARM Alpine／musl	事前ビルド済み	—	—	非対応
linuxmusl-x64	x86-64 Alpine／musl（node:*-alpine イメージ）	事前ビルド済み	—	—	非対応（CI：node:22-alpine コンテナーでこの判定を検証）
win32-arm64	ARM 搭載 Windows（Snapdragon、Windows 11 ARM を実行する Apple シリコン VM）	事前ビルド済み	—	事前ビルド済み	非対応（CI：windows-11-arm でこの判定を検証）
win32-x64	x86-64 Windows 10/11	事前ビルド済み	事前ビルド済み	事前ビルド済み	対応（CI：windows-latest、実験的）
その他のターゲット	FreeBSD、32 ビット x86 など	コンパイル	—	—	非対応
すべてのネイティブ依存関係（better-sqlite3、sqlite-vec、onnxruntime-node）は N-API に対応しており、Node のバージョンに依存しません。同じバイナリが、奇数のメジャーバージョン（非 LTS）を含む、すべての Node メジャーバージョン 22 以上で動作します。scripts/preflight.cjs から node scripts/supported-platforms.cjs --write で生成されます。--check はテストスイートで実行されます。

現在の状況を判断する方法は 3 つあります。

• npx @devinmlowe/engram preflight（またはインストール後は engram preflight、チェックアウト内では node scripts/preflight.cjs）を実行すると、ネイティブモジュールごとに 1 行ずつ表示されます。表示内容は [ok] prebuilt、[warn] compiled locally / will compile (needs python3 + C++ toolchain)、[FAIL] unsupported、[--] unknown (<reason>) で、その後に 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 の「Desktop development with C++」ワークロード）。判定は静的なターゲットテーブルに基づきます（すべてのネイティブモジュールは N-API のため、Node のメジャーバージョンは関係ありません）。インストール後は、配布されたバイナリが実際に node_modules にあることも確認します。バンドル済みの prebuilds/<target>.node の代わりに build/Release/better_sqlite3.node がある場合は、node-gyp によってローカルでコンパイルされています。--json は構造化された結果を出力します。--strict は [FAIL] が 1 つでもあると終了コード 1 で終了します。--expect prebuilt（または --expect better-sqlite3=prebuilt,sqlite-vec=unsupported）は判定結果が一致しないと終了コード 1 で終了します。これは、依存関係の更新で prebuild が削除された場合に CI を失敗させるための方法です。npm_config_platform / npm_config_arch / npm_config_target_arch / npm_config_libc でターゲットを上書きできます。
• npm install は、この preflight を失敗しても処理を中断しない postinstall hook として実行します（ENGRAM_SKIP_PREFLIGHT=1 で表示を抑制できます）。インストールが失敗することはありません。package.json では、インストール可能なプラットフォームを制限する os / cpu フィールドを意図的に宣言していません。これらを宣言すると、一覧にないターゲットでもツールチェーンが動作する環境でインストールできなくなるためです。
• engram doctor はビルド後のチェック一式を実行します。better-sqlite3 と sqlite-vec の行末は prebuilt — … または compiled locally — … となり、アップグレード時に node-gyp によるコンパイルへ予期せず切り替わったのか、それとも prebuild が使われたのかを確認できます。よくある原因は、オフラインまたはプロキシ経由でのインストール、あるいは npm_config_build_from_source です。

注意事項：Windows on ARM、armv7、Alpine/musl。 sqlite-vec は win32-arm64 または linux-arm（armv7）向けのバイナリを公開していません。また、Linux ビルドは onnxruntime-node と同様に glibc 専用です（ld-linux が必要で、gcompat を使っても musl では読み込めません）。better-sqlite3 自体は win32-arm64 と musl 向けの prebuild を提供しています（13.x では 32-bit の linux-arm 向け prebuild が削除されたため、armv7 ではソースからコンパイルされます）。そのため、該当環境でも npm install は 成功 しますが、その後 engram init は sqlite-vec の読み込みに失敗します。preflight は事前に [FAIL] sqlite-vec: unsupported と報告します。Windows on ARM で現実的な回避策は、x64 版 Node.js をインストールすることです。Windows 11 ではエミュレーションで実行され、win32-x64 向けの prebuild を読み込めます（低速で、CI ではテストされていません）。armv7 ボードでは、64-bit OS イメージ（linux-arm64）を使用してください。Alpine では、glibc イメージ（node:22-bookworm-slim）を使用してください。 npm 10 は、better-sqlite3 13 に対して今も node-gyp を実行します。 パッケージにはバイナリが同梱されていますが、ロックファイルに gypfile: false が含まれていないため、npm 10（Node 22 に同梱されている npm）はインストール時に暗黙的に node-gyp rebuild を実行します。同梱済みの prebuild が一致すれば binding.gyp は何もコンパイルしませんが、それでも node-gyp configure には Python 3 と Node ヘッダーが必要です。Node のバージョンごとに一度、これらは nodejs.org からダウンロードされます（~/.cache/node-gyp にキャッシュされます）。そのため、prebuild のあるターゲットでも、オフライン環境やプロキシ経由のインストールで失敗することがあります。Windows では、Node 22 のインストールに node-gyp が認識する Visual Studio（C++ ワークロードを含む 2019／2022 Build Tools）と Python 3 が必要になります。node-gyp configure は binding.gyp を読み取る前に could not find a version of Visual Studio 2017 or newer で失敗するためです。CI の windows-latest, node 22 ジョブで、まさにこの現象が確認できます。代わりに npm 11（Node 24、または Node 22 で npm install -g npm@11）はスクリプトをスキップするため、これが最も簡単な回避策です。どちらの場合も、preflight は [ok] better-sqlite3: prebuilt — prebuilds/<target>.node is bundled in the package と報告します。

それ以外の環境で必要なツールチェーン。 対象環境向けの prebuild が better-sqlite3 に同梱されていない場合（表にないプラットフォーム、たとえば armv7 や FreeBSD）、npm install は node-gyp を使ってソースからコンパイルします。そのため、C++ ツールチェーンと Python 3 が必要です。

• Windows：Visual Studio 2022 Build Tools と「C++ によるデスクトップ開発」ワークロード（MSVC コンパイラと Windows SDK）、および Python 3。node-gyp はこれらを自動的に検出します。誤った Visual Studio が選択された場合は、npm config set msvs_version 2022 を実行してください。
• Linux：gcc／g++、make、python3 — Debian／Ubuntu では sudo apt install build-essential python3、Fedora では sudo dnf install gcc-c++ make python3、Alpine では apk add build-base python3。
• macOS：Xcode Command Line Tools（xcode-select --install）。

CI では、x64 Linux、arm64 Linux（ubuntu-24.04-arm）、arm64 macOS、x64 Windows（実験的）で Node 22 と 24 の lint およびテストスイート全体を実行します。また、それぞれで preflight --strict --expect prebuilt を実行するため、依存関係の更新で prebuild がなくなった場合は、ユーザーの環境ではなく CI で失敗します。さらに、windows-11-arm と node:22-alpine（musl）コンテナーでは、ドキュメントに記載された「非対応」という判定になることを検証します。Dependabot はネイティブモジュールの更新を個別にグループ化し、手動で prebuild を確認できるよう、それらには native-dep ラベルが付けられます。

コア原則

メモリは検索ではありません

Engram は認知システムです。意味を抽出し、パターンを統合し、矛盾を検出し、新たに生まれるつながりを提示します。生の会話は入力であり、出力ではありません。

トークンの節度

メモリの注入は必要最小限にとどめる必要があります。取得したメモリは呼び出し元が指定したトークン予算内に収め、冒頭に配置しやすい形式で整え、段階的に開示します。まずポインターを提示し、全文はリクエストされた場合にのみ提示します。

創発的な発見

Zettelkasten と同様、価値はつながりにあります。機会を捉えた双方向リンク、グラフの密度から生まれる Maps of Content、そしてコレクション全体のパターンに気づく司書のような役割を果たす dream state デーモン。

ローカル優先、オフライン対応

すべての処理はローカルで実行されます。例外は、抽出や要約に使うオプションの API 呼び出しだけです（完全なオフライン運用のため、Ollama を介したローカルモデルに置き換えられます）。

アーキテクチャ

共有コアインフラストラクチャを備えた 4 つのドメイン：

• episodic/ — 会話アーカイブの取り込み、インデックス作成、エピソード検索
• semantic/ — ナレッジの抽出、統合、セマンティック検索
• graph/ — エンティティ／関係性グラフ、トピッククラスター、ファイル構造のインデックス作成、グラフ走査
• dream/ — 自律的な統合パイプライン（取り込み → 抽出 → 統合 → 振り返り → プルーニング）
• interfaces/ — CLI、MCP サーバー、ウェブ可視化
• _core/ — 共有インフラストラクチャ（設定、DB、型、埋め込み、検索、LLM、キャッシュ）
• decisions/ — アーキテクチャ決定記録

MCP サーバー

LLM エージェントのメモリ操作用ツールを16個提供します。

ツール	目的
recall	トークン予算付きのハイブリッド検索（ベクトル＋FTS5＋グラフ）を行います。返されたメモリを強化し（FSRS の記録処理。reinforce: false で無効化できます）、呼び出しごとの scope / read_scopes を受け付けます
remember	単一のメモリ（事実、決定、パターンなど）を保存します
show	会話全体またはメモリのコンテキストを取得します
explore	エンティティから固定深度でグラフをたどります。呼び出しごとの scope / read_scopes に対応しています（#25）
reflect	グラフを分析します — コミュニティ、橋渡し、時間的パターン
recall_session	セッション追跡と予算を備えた、状態を保持する反復検索を行います
recall_drill	特定の検索結果を予算を差し引きながら詳細に掘り下げます
explore_selective	関連性フィルタリングを備えた、モデル主導の選択的なグラフ走査を行います。read_scopes に対応しています
remember_batch	エンティティのリンク付けと重複排除を行いながら、メモリを一括取り込みします
fetch_snippets	ファイル内の複数範囲のスニペットを取得します（最大20範囲）
index_file_structure	ファイル構造を解析してグラフエンティティに変換します（複数言語に対応）
scan_file	関数コンテキストの検出機能を備えた、正規表現ベースのファイルスキャンを行います
commitments	追跡対象のコミットメント（約束、意図、他者に対するフォローアップ）を一覧表示します — 期限超過のものが先に表示されます。read_scopes に対応しています
commitments_update	コミットメントを完了、破棄、または置き換え済みとしてマークします
ingest_turn	外部エージェントのセッションで、ユーザー／アシスタントの1ターンを記録します（session_id、turn_index、scope、user_text、assistant_text）。エピソード層に冪等なアップサートを行い、抽出されたメモリはスコープを引き継ぎます
forget	ユーザーが誤りまたは古くなったと述べたメモリを削除します（#55）。memory_id（呼び出されたすべての <semantic> に含まれる id）は1回の呼び出しで処理されます。query は ID 付きの候補を返し、confirm: true かつ曖昧さのない一致が1件の場合にのみ処理します。ENGRAM_FORGET_RETENTION_DAYS の期間はソフト削除として保持されます（ベクトル／FTS の行は直ちに削除され、クライアント名とともに変更ログに記録され、dream による再抽出の対象にはなりません）。hard: true は完全に削除します。read_scopes に対応しています。scope: "global" は、サーバー環境変数で読み取りスコープが固定されていない場合に限り、その設定を上書きします（#109）

トランスポート：stdio（デフォルト）と HTTP

dist/interfaces/mcp/server.js（およびプラグインが実行する engram mcp）は、 デフォルトでstdioを使用します。これは「インストールと初回実行」の .mcp.json の例で使用されている方式です。--http を指定して起動すると、 代わりにStreamable HTTPで提供します。

node dist/interfaces/mcp/server.js --http            # http://127.0.0.1:9907/mcp
node dist/interfaces/mcp/server.js --http --port 9910

HTTP モードでは POST /mcp（クライアントごとに1つの MCP セッションを使用し、 Mcp-Session-Id ヘッダーでルーティング）と、JSON を返す GET /health を公開します。 バインド先は 127.0.0.1 のみです。Streamable HTTP 対応クライアントから接続してください。

{ "mcpServers": { "engram": { "type": "http", "url": "http://127.0.0.1:9907/mcp" } } }

（デーモンが /health に応答すると、engram mcp install <host> はこの内容をそのまま書き込みます。トークンが設定されている場合は、トークンヘッダーの参照も書き込みます。）

HTTP モードでは、すべてのツール呼び出しが node:worker_threads のプールで実行されるため、 数秒かかる recall が /health、ハンドシェイク、または他のクライアントをブロックすることはありません。 各ワーカーは、それぞれ独自の SQLite 接続と埋め込みモデルを使用します。stdio モードでは、 ワーカーは起動されません。

stdio は実行中のデーモンに中継します。 stdio で起動するとき（engram mcp、プラグインの npx コマンド、node dist/interfaces/mcp/server.js）、まず GET http://127.0.0.1:<port>/health を確認します（--port、それ以外は ENGRAM_MCP_PORT、それも未設定なら 9907、 タイムアウトは1.5秒）。engram デーモンが応答した場合、プロセスは薄いプロキシとして動作します — デーモンの /mcp に接続する MCP クライアントと、stdio 上で tools/list、tools/call、ping を転送する MCP サーバーとして動作し、データベースを開いたり埋め込みモデルを読み込んだりすることはありません。 そのため、すべてのホストが1つのウォームなデーモンを共有します。そうでない場合は、従来どおり プロセス内でフルサーバーを実行します。どちらの方式で動作しているかは、stderr の1行で示されます。

Engram MCP: bridging stdio to http://127.0.0.1:9907/mcp (daemon healthy)
Engram MCP: running inline (no daemon on :9907 (ECONNREFUSED))

engram mcp --standalone（またはサーバーの環境変数で ENGRAM_MCP_STANDALONE=1）を指定すると、インライン実行が強制されます。また、その環境変数で ENGRAM_SCOPE／ENGRAM_READ_SCOPES を指定した場合も同様です（これらはこのプロセスにスコープを適用します。デーモンは無視します。#87）。ENGRAM_DB_PATH が設定されている場合、デーモンの /health が同じ dbPath を報告したときに限り、ブリッジが使用されます。デーモンがトークンを要求する場合、ブリッジは自身の環境変数から Authorization: Bearer $ENGRAM_MCP_TOKEN を転送し、ホストの clientInfo を使ってデーモンのセッションを再オープンします（そのため、forget には引き続き実際の実行者が記録されます）。また、再接続を1回行うことで、デーモンの再起動（engram update）後も動作します。

変数	デフォルト	用途
ENGRAM_HTTP_WORKERS	2	HTTP モードでのワーカー数（0 = ツール呼び出しをメインスレッドでインライン実行）
ENGRAM_WORKER_TIMEOUT_MS	8000	呼び出しごとのタイムアウト。remember、remember_batch、index_file_structure、reflect --refresh には、より長い最低タイムアウトが適用されます。タイムアウトの2倍の時間が経過しても応答しないワーカーは強制終了され、再起動されます
ENGRAM_MCP_TOKEN	—	設定すると、/mcp は Authorization: Bearer <token> を要求します（それ以外の場合は401）。監視プロセスが使用できるよう、/health は公開されたままです。デーモンがループバック以外のアドレスにバインドする前に設定が必要です
ENGRAM_MCP_HOST	127.0.0.1	バインドアドレス。ENGRAM_MCP_TOKEN が設定されていない場合、ループバック以外へのバインドは拒否されます
ENGRAM_MCP_STANDALONE	—	1 を指定すると、デーモンが正常な場合でも、stdio で起動したプロセスはインライン実行されます（--standalone と同じです）

認証。 デフォルトでは、どちらの HTTP サーバーもアクセス制御をループバックバインドに依存しています。 127.0.0.1 にアクセスできるユーザー（ほかのローカルユーザーやリバースプロキシなど）は、メモリーストアに対する読み書きの完全なアクセス権を持ちます。ベアラートークンを必須にするには、ENGRAM_MCP_TOKEN（監視対象のデーモンでは ~/.config/engram/env 内）を設定してください。Streamable-HTTP クライアントはヘッダーとしてトークンを送信します。例： { "type": "http", "url": "http://127.0.0.1:9907/mcp", "headers": { "Authorization": "Bearer <token>" } }。 Hermes プラグインは engram.json の token から読み取ります。engram mcp install はトークンをそのまま書き込むことはありません。代わりに変数を参照します（Claude Code では Bearer ${ENGRAM_MCP_TOKEN}、Codex では bearer_token_env_var、Cursor では Bearer ${env:ENGRAM_MCP_TOKEN}）。そのため、シークレットは ~/.config/engram/env に保持されます。ホストの環境変数から値を解決できない場合は、engram mcp status で確認できます。トークンは定時間比較で照合され、ログに記録されることはありません。ビジュアライザーでは ENGRAM_WEB_TOKEN を使用し、設定されていない場合は ENGRAM_MCP_TOKEN にフォールバックします。 Web Visualization を参照してください。

ワーカープールの内部実装（worker-pool.ts、dispatch.ts、worker.ts）については、CLAUDE.md の「MCP Server Transports」セクションを参照してください。

その他のエージェントとの統合（Codex CLI、Cursor、カスタムホスト）

engram mcp install codex／cursor で MCP ツールを登録できます（ホストの登録 を参照）。engram mcp install codex && engram mcp install cursor を実行すると、両方のホストで1つの engram.db を共有できるため、Codex での remember を Cursor から recall できます。自動リコールフックと指示ブロックについては、docs/integrate-your-agent.md をご覧ください。このドキュメントは、接続先のホスト上で動作する AI エージェントに渡すことを想定しています。公開契約（エンドポイント、ハンドシェイク、ツール、スコープ）と、実装すべき3つの動作（各ターンの前に自動リコールを行う、明示的な MCP ツールを用意する、remember で記録する）が、検証手順と実際に動作する Codex CLI の例とともに記載されています。interfaces/hermes-plugin/ の Hermes Agent プロバイダーが、リファレンス実装です。

既存のインストールを更新する

データはリポジトリの外部に保存されます（engram doctor で実際に使用されるデータディレクトリとデータベースが表示されます）。スキーマのマイグレーションは追加方式で、データベースを開くたびに実行されます。残りの作業は engram update が行います。プラットフォームごとにコマンドは1つです。

engram update --check   # current vs available (git tag or npm dist-tag), nothing else; cached 24 h
engram update --plan    # read-only: install kind, every dir holding an engram.db, model cache,
                        # every service and how it will be restarted, plugin deploy targets
engram update           # the controlled upgrade (asks once; --yes for scripts, --no-backup to skip the backup)
engram update --rollback            # undo the last update: previous code back, services restarted, verified
engram update --rollback --restore-data   # …and put the pre-update backup of the data dir back

engram update --plan    # identical on Windows (Task Scheduler tasks under \Engram\)
engram update --yes

実行時の処理順序（--plan の出力には、この一覧にお使いのマシンのパスが反映されます）：

1. バックアップ：WAL をチェックポイント処理した後、データディレクトリ（engram.db、-wal／-shm、archive/）を、隣接する <data dir>.backup-<timestamp> にバックアップします。
2. 停止：スーパーバイザー経由で、実行中の engram サービスをすべて停止します。順序は dream、MCP HTTP デーモン、ビジュアライザーです（launchd／systemd ユーザーユニット／タスクスケジューラ）。スーパーバイザーがない状態でポートに応答するデーモンは処理を妨げます。手動で停止するか、先にスーパーバイザーをインストールしてください。
3. スナップショット：行数を記録します（engram stats --json）。
4. モデルキャッシュ：0.4.0 より前のキャッシュが node_modules/@xenova/transformers/.cache に残っている場合は、npm が node_modules を操作する前に、解決されたキャッシュディレクトリ（デフォルトは <data dir>/models）に移動します。models/ は再ダウンロード可能なためバックアップされません。キャッシュがない場合、ロールバック時に再ダウンロードされます。
5. コード：チェックアウトの場合は git pull --ff-only と npm ci を実行します（作業ツリーに変更があると処理を妨げます）。npm インストールの場合は npm install -g @devinmlowe/engram@<version> を実行します。
6. マイグレーション：データベースが1つだけ存在する場所が該当する場合、0.2.0 より前のデータディレクトリを解決されたデータディレクトリに移動します（両方のディレクトリにデータベースがある場合は拒否します）。次に、新しいビルドでデータベースを一度開き、スキーマのマイグレーションを実行します。
7. 再起動：MCP デーモン、次にビジュアライザーを再起動し、それぞれ /health が応答するまで待ちます。dream のスケジュールを再度有効にします。Hermes プラグイン（interfaces/hermes-plugin/deploy.sh）を、プラグインがあるすべてのプロファイルに再デプロイします。ゲートウェイも再起動します。（Claude Code プラグインには手を加えません。マーケットプレイス経由で更新されるためです。/plugin update engram@engram を実行すると、古いデーモンに接続していた stdio ブリッジは新しいデーモンに再接続します。）
8. 検証：engram doctor、/health、および減少していないことを確認する engram stats の件数をチェックします。コードの切り替え後にいずれかの手順が失敗した場合、以下のロールバックが提示されます。--yes を指定するとロールバックが実行され、ターミナルでは Roll back to <previous>? [y/N] と尋ねられます。スクリプトで --yes を指定しなかった場合は、実行するコマンドがそのまま表示されます。何が起きても、サービスは再開されます。

ロールバック

変更を加える前に、engram update はロールバック計画を <data dir>/updates/<stamp>.json に記録します（直近の 10 件を保持します。 engram update --list-rollbacks で一覧表示できます）。計画には、以前のバージョンと git sha、インストール種別とルート、バックアップディレクトリ、実行中だったサービスと その起動コマンド、プラグインのデプロイ先、更新先のバージョン、 データベースのスキーマバージョン、更新前の行数、各手順で進む progress マーカーが含まれます。そのため、更新が手順 1 で中断した場合でもファイルが存在し、 ロールバック時に更新がどこまで進んだかがわかります。

engram update --rollback                  # the most recent plan; --rollback <stamp> for an older one
engram update --rollback --restore-data   # also restore the backup (everything written since is discarded)

ロールバックは、デフォルトではコードのみを対象とします（判断 #66）。サービスを停止 → git checkout <previous sha> && npm ci または npm install -g @devinmlowe/engram@<previous> →復元したビルドを子プロセスで使って engram migrate schema を実行 → 実行中だったサービスを再起動 → 同じ検証（バージョン、doctor、/health、 スナップショット以上の行数）を行います。engram.db には更新後に書き込まれた内容が すべて保持されます。スキーマ移行は追加のみのため、以前のビルドは新しいデータベースを読み込み、 認識しない列やテーブルを無視します（注意点が表示されます）。バックアップは --restore-data を指定した場合、またはロールバックのきっかけとなった検証の失敗で 行数が更新前のスナップショットを下回っていた場合にのみ復元されます。暗黙に復元されることはありません。 --restore-data は engram.db と WAL、archive/ を復元します（アーカイブはマージされ、 バックアップ側が優先されます）。更新時に --no-backup を指定していた場合は拒否されます。 すべてのロールバックで、実行されたモードと models/ がバックアップ対象に含まれないことが 表示されます（#54）。古いビルドでは読み進められない移行をリリースに含める場合 （src/_core/db/schema.ts の BREAKING_MIGRATIONS。現在は空です）、それをまたぐ コードのみのロールバックは拒否され、その旨が表示されます。--restore-data は引き続き実行できます。

どの engram が実行されるのか？

Homebrew の node と nvm の node という 2 つのグローバルツリーに、それぞれ bin/engram があると、npm i -g は一方をアップグレードする一方で、シェルはもう一方を 実行し続けることがあります。engram doctor の install path チェックは、 PATH 上のすべての engram を一覧表示し、複数ある場合、または先頭のものが engram update でアップグレードされるインストール先と異なる場合に警告します （[--]。失敗にはなりません）。修正方法（もう一方のツリーの npm で npm uninstall -g @devinmlowe/engram を実行するか、PATH の順序を変更すること）も表示されます。 engram update --plan でも同じ警告が表示されます。

日次バージョン通知

engram update --check は、<data dir>/cache/update-check.json に結果を24時間キャッシュします。engram doctor、health、stats、search、sync、reflect は、新しいバージョンが判明している場合、stderr に1行表示します（engram 0.4.0 available (you have 0.3.0) — engram update）。キャッシュの更新は1日1回までです（--json の場合や MCP サーバーからは表示されません）。また、デーモンの /health JSON には、同じキャッシュに基づく update: {current, available, checkedAt} が含まれます。自動で更新されることはありません。ENGRAM_NO_UPDATE_CHECK=1 を設定すると、自動確認と通知が無効になります（明示的に engram update --check を実行した場合は確認し、引き続き有効なキャッシュエントリーを再利用します）。

engram migrate [data-dir|model-cache|schema] [--dry-run] は、手動で更新するインストール向けに、ステップ4と6を個別に冪等に実行します（デフォルトが適用され、移行対象のレガシーデータが残っていない場合、model-cache は何も行いません）。

リリースの変更内容については、CHANGELOG.md をご覧ください。たとえば、0.2.0 では最初の dream 実行時にすべての会話が一度再抽出されます（ENGRAM_DREAM_MAX_CONVERSATIONS で上限を設定してください）。

手動での更新。 ご自身で実行する場合も、同じ手順です。

git fetch origin && git status --short   # resolve any local changes first
git pull origin main
npm ci                                   # exact dependencies; rebuilds via "prepare", runs the install preflight
engram migrate                           # data dir + model cache + schema (see --dry-run first)

npm でインストールした場合は、npm install -g @devinmlowe/engram@latest を実行してから、engram migrate を実行します。

その後、実行中のプロセスを管理しているものを再起動し、新しい dist/ 出力を読み込ませてください（プラグインを再デプロイし、Hermes ゲートウェイを再起動してください）。

プラットフォーム	MCP HTTP デーモン	Dream デーモン	ビジュアライザー
macOS（launchd）	./scripts/install-mcp-daemon.sh restart	launchctl kickstart -k gui/$(id -u)/com.engram.dreamstate	./scripts/install-visualizer.sh restart
Windows（タスク スケジューラ）	.\scripts\install-mcp-daemon.ps1 restart	.\scripts\install-daemon.ps1 restart	.\scripts\install-visualizer.ps1 restart
Linux（systemd）	./scripts/install-mcp-daemon.sh restart（systemctl --user restart engram-mcp）	systemctl --user restart engram-dream	ご自身のスーパーバイザーで実行してください

実際にインストールされているサービスだけを再起動してください（各インストーラーの status で確認できます）。手動で起動した node dist/interfaces/mcp/server.js --http は監視されていないため、手動で停止して再起動するか、install-mcp-daemon.sh install で置き換える必要があります。

再起動後に確認します。

engram doctor      # node, native modules, model cache, ollama tier, effective data dir, env file, install path, mcp daemon /health, registered hosts, extraction smoke
engram health      # database, embedding model, MCP entry point
engram stats       # counts must match the pre-update numbers
engram search "smoke test"   # end-to-end recall through the new build

Windows：安全な更新とデータディレクトリの移行

0.2.0 では、Windows のデフォルトのデータディレクトリが %USERPROFILE%\.local\share\engram から %LOCALAPPDATA%\engram に変更されました。 それ以前にインストールした場合、データベースは旧パスに残ります。アップグレード後は、データを移動するか ENGRAM_DATA_DIR を設定しない限り、すべての engram コマンドと MCP デーモンが新しい空のデータベースを開きます。engram update がこの処理を行います（手順 6）。手動で更新する場合は、事前に次の確認を行ってください。

engram doctor --json          # "data dir" check: which engram.db this process uses, and a warning
                              # if a populated legacy database exists that it would ignore
Test-Path "$env:USERPROFILE\.local\share\engram\engram.db"   # legacy location
Test-Path "$env:LOCALAPPDATA\engram\engram.db"               # 0.2.0+ default
engram stats                  # write these counts down; they must match after the update

• アップグレード中に engram init を実行しないでください。有効なパスに新しいデータベースが作成されます。実行するのは、本当に新規インストールする場合だけです。
• データを移動する（engram migrate data-dir を実行するか、手動で engram.db、 engram.db-wal、engram.db-shm、archive\、logs\ を）%LOCALAPPDATA%\engram に移すか、ユーザースコープの環境変数を設定して、現在の場所に保持します：setx ENGRAM_DATA_DIR "$env:USERPROFILE\.local\share\engram" （データベースファイルだけの場合は ENGRAM_DB_PATH）。ユーザースコープが重要です。タスク スケジューラのタスクはこの設定を継承しますが、インストール元のシェルは継承しません。
• まず、アクティブなデータディレクトリをバックアップしてください （Copy-Item -Recurse $dataDir "$dataDir.backup-$(Get-Date -Format yyyyMMdd-HHmm)"）。
• モデルの重みはデフォルトで %LOCALAPPDATA%\engram\models に保存されます（または ENGRAM_MODEL_CACHE_DIR の指定先）。そのため、npm ci によって削除されることはありません。

インストールと再起動。 各インストーラーの restart は、タスクが存在することを前提としています。以前のインストールでは、ビジュアライザーのタスクはあっても MCP タスクがない場合や、MCP プロセスが手動で起動されたままの場合があります。まず確認して、適切な動詞を選んでください。

.\scripts\install-mcp-daemon.ps1 status    # installed / taskState / healthy / dataDir / dbPath / legacyDbPath
.\scripts\install-mcp-daemon.ps1 install   # no task yet (re-runnable; re-registers with the current paths)
.\scripts\install-mcp-daemon.ps1 restart   # task exists
Get-ScheduledTask -TaskPath '\Engram\'     # which of MCP, Dream, Visualizer are actually installed

インストールされているものだけを再起動してください。インストーラーは、CLI が解決するものと同じデータディレクトリ（%LOCALAPPDATA%\engram または ENGRAM_DATA_DIR）をデフォルトで使用し、-DataDir / -DbPath を明示的に指定できます。CLI とフックが使用するものと同じディレクトリを渡してください。status には、タスクの登録時に指定された内容が表示されます。

ポート上の古いプロセス。 ポート 9907 で応答があるにもかかわらず、status にタスクの再起動中または healthy False と表示される場合、スーパーバイザーが管理していないプロセスがポートを占有しています。

Get-NetTCPConnection -LocalPort 9907 -State Listen | Select-Object OwningProcess
Get-Process -Id <pid> | Select-Object Id, ProcessName, Path, CommandLine
Stop-Process -Id <pid>                                # only if it is an engram node.exe you started by hand
.\scripts\install-mcp-daemon.ps1 restart              # the task's own runner now binds the port

uninstall と stop は、コマンドラインを使って残存する node.exe / run-mcp-daemon.ps1 プロセスも検出して終了するため、古い PID ファイルが孤立したプロセスを残すことはありません。

更新後の検証（データの保持と利用可能性の両方を確認します）：

engram doctor                 # every check [ok]; "data dir" names the populated database
engram health
engram stats                  # counts equal the pre-update numbers
engram search "smoke test"
.\scripts\install-mcp-daemon.ps1 status    # taskState Running, healthy True
Invoke-RestMethod http://127.0.0.1:9907/health
# MCP handshake + tool listing through the daemon:
$init = @{ jsonrpc='2.0'; id=1; method='initialize'; params=@{ protocolVersion='2025-03-26'; capabilities=@{}; clientInfo=@{ name='check'; version='0' } } } | ConvertTo-Json -Depth 5
$r = Invoke-WebRequest http://127.0.0.1:9907/mcp -Method Post -ContentType 'application/json' -Headers @{ Accept='application/json, text/event-stream' } -Body $init
$sid = $r.Headers['Mcp-Session-Id']
Invoke-WebRequest http://127.0.0.1:9907/mcp -Method Post -ContentType 'application/json' -Headers @{ Accept='application/json, text/event-stream'; 'Mcp-Session-Id'="$sid" } -Body '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | Select-Object -ExpandProperty Content

ビジュアライザーがインストールされている場合：.\scripts\install-visualizer.ps1 status と Invoke-RestMethod http://127.0.0.1:3001/api/health。

CLI

engram init            # Initialize database + download embedding model
engram sync            # Ingest conversations from Claude Code projects
engram search <query>  # Hybrid search across all memory layers
engram remember <text> # Store a memory
engram extract         # LLM-based fact extraction from a conversation
engram dream           # Run autonomous consolidation pipeline (--force re-extracts unchanged conversations)
engram reflect         # Show emergent graph patterns
engram explore <name>  # Explore entity connections
engram entities        # List/search entities
engram relationships   # Show relationships for an entity
engram stats           # Database statistics (--json: the row counts `engram update` compares before/after)
engram health          # System health check (database, model, Ollama, MCP entry point)
engram doctor          # Runtime diagnostics: node, platform/arch, better-sqlite3, sqlite-vec, model cache, ollama tier, llm providers, data dir, env file, install path, mcp daemon, hosts, extraction smoke (--json, --fix [--yes], --strict, --no-smoke)
engram setup           # First run in one command: doctor → init → sync → mcp install → all three services → doctor --fix → extraction smoke → summary (--yes, --no-sync/--sync, --no-daemons/--daemons=<ids>, --host <id...>, --no-smoke, --json)
engram update          # Controlled self-update: backup, stop services, pull/npm install, migrate, restart, verify (--check, --plan, --yes, --no-backup, --rollback [stamp], --restore-data, --list-rollbacks)
engram migrate [topic] # Install/data migration: data-dir | model-cache | schema | all; idempotent, --dry-run lists every action
engram memories list|show|edit|delete|restore|purge|log  # Inspect and curate memories: provenance, edit, forget (soft delete + retention), restore, purge a conversation, change log
engram validate [--fix]  # Store integrity (embeddings, FTS, no vector/FTS rows for forgotten memories; --fix repairs)
engram backfill-event-ts  # Backfill event-time timestamps (temporal recall)
engram commitments [status]        # List tracked commitments (same XML as the MCP tool)
engram commitment-done <id>        # Mark a commitment done (--status dropped|superseded)
engram commitments-extract <conv>  # Re-scan one conversation (no checkpoint; proves dedupe)
engram export [--out f] [--scope s...] [--include-inactive] [--kinds ...]  # JSONL v1 of memories/entities/relationships/commitments (no embeddings)
engram import <file> [--scope override] [--dry-run]  # Idempotent by id (newer wins); vectors + FTS regenerated from content
engram mcp             # Start the MCP server (stdio; see Transports section)
engram mcp install <host> [--all] [--project] [--transport http|stdio] [--dry-run] [--force] [--inline-token] [--json]  # Register with claude | codex | cursor | hermes
engram mcp uninstall <host> [--project]   # Remove the engram entry (previous content in <file>.bak)
engram mcp status [--json]                # Every host: registered, this install?, daemon /health, ENGRAM_MCP_TOKEN resolves?

Web Visualization

localhost:3001 でインタラクティブなナレッジグラフを可視化できます。

Force Graph (/graph)	Depth View (/graph/depth)
Obsidian に着想を得た、Canvas 上の 2D 力指向グラフです。ノードのサイズは言及数に応じて変わり（平方根スケール）、エンティティの種類ごとに色分けされ、次数に応じて明るさが変わります。中心が暗くなるグラデーションを設定可能なエッジで描画します。言及数のしきい値スライダー、種類のフィルターピル、近傍ノードをハイライトするテキスト検索、クリックによるフォーカス、ノードのドラッグに対応しています。	縦軸で関連性を表す Three.js の 3D グラフです。関連性は、再現性（30％）、言及頻度（25％）、橋渡しスコア（20％）、作成からの経過期間（10％）、次数（15％）を重み付けして組み合わせた値です。古く、つながりの少ないノードは下に沈み、アクティブなハブは上に浮かびます。衛星ノードをハブに引き寄せる重力パスと、最初のノードから現在までグラフの履歴を再生する成長アニメーションも含まれます。
Galaxy View (/graph/galaxy)	Word Cloud (/words)
ハブノード（次数、橋渡しスコア、言及数が高いノード）が重力の中心となり、それぞれが 3D 空間内に固有の軌道面を形成します。衛星ノードは、集積の強さ（エッジの重み）に基づいてハブの周囲を公転し、近傍ノードとの Jaccard 類似度によって角度が決まります。ハブの反発、衛星の引き寄せ、円盤の平坦化、軌道の整列、橋渡しノードの引き寄せ、標準的な電荷という 6 つのカスタム力が、生きた太陽系のような表現を生み出します。ハブのしきい値、円盤の平坦さ、システム間隔を設定できます。	エピソード記憶内のユーザーメッセージから作成された D3 ワードクラウドです。単語のサイズは頻度を平方根スケールで表し、広範なストップワードリストと 16 進ハッシュ検出器を使ってフィルタリングします。Catppuccin Mocha の 12 色パレットを使用し、Archimedean スパイラルで配置します。回転は横向き 65％、縦向き 20％、斜め 15％の割合です。ホバーすると言及数が表示され、10 秒ごとのライブポーリングで更新され、変更時にはパルスアニメーションが表示されます。

• Dream Control — ライブのパイプラインフェーズ追跡とプログレスバー（このページは /graph/api/dream/status をポーリングします）
• Live Updates — 各ビューは 1.5 秒ごとに対応する api/diff ルートをポーリングします。WAL ウォッチャーは、データベースが変更されるとサーバーのキャッシュをリセットします

起動方法：npx tsx src/interfaces/web/server.ts

Authentication. デフォルトではループバック接続のみを受け付け、認証は不要です。ENGRAM_WEB_TOKEN （または ENGRAM_MCP_TOKEN）を設定すると、/api/health 以外のすべてのルートでトークンが必要になります。API クライアントでは Authorization: Bearer <token> として渡すか、任意のページを一度 ?token=<token> 付きで開くと、 サーバーがそのページからの API 呼び出し用に HttpOnly Cookie を設定します。トークンを設定せずに ループバック以外の ENGRAM_BIND にバインドしようとすると、起動時に拒否されます。

Windows に永続的にインストールする場合は、scripts/install-visualizer.ps1 を使用してください。macOS の launchd 用の方法は引き続き scripts/install-visualizer.sh を使用します。

Search

Reciprocal Rank Fusion によって 3 つの情報源を組み合わせるハイブリッド検索です。

• Vector — nomic-embed-text（384 次元）による意味的類似性検索。MiniLM によるフォールバックに対応
• FTS5 — SQLite の全文検索で、会話、記憶、エンティティを検索
• Graph — エンティティの探索と、関係性を考慮したコンテキストの拡張

すべての検索レスポンスは、呼び出し元が指定したトークン予算を尊重します。ステートフルセッションでは、予算を追跡しながら反復的に検索を絞り込めます。

Dream Pipeline

人間の記憶の統合を模倣する、自律的な統合処理：

flowchart LR
    subgraph dream["Dream Daemon"]
        direction LR
        I[Ingest] --> E[Extract] --> C[Consolidate] --> R[Reflect] --> P[Prune]
    end

    subgraph episodic["Episodic"]
        sync[sync]
        store[store]
    end

    subgraph semantic["Semantic"]
        extractor[extractor]
        consolidator[consolidator]
        decay[decay]
    end

    subgraph graph["Graph"]
        gextractor[extractor]
        reflection[reflection]
    end

    subgraph core["_core"]
        llm[llm]
        db[db]
        embeddings[embeddings]
    end

    I -- "discover & index\nconversations" --> sync
    sync -- "persist\nexchanges" --> store
    E -- "extract facts" --> extractor
    E -- "extract entities\n& relationships" --> gextractor
    C -- "dedup, merge,\nconflict detect" --> consolidator
    R -- "communities, bridges,\ntemporal patterns" --> reflection
    P -- "FSRS decay,\nlow-value removal" --> decay

    extractor --> llm
    gextractor --> llm
    reflection --> llm
    store --> db
    consolidator --> embeddings
    extractor --> embeddings

1. 取り込み — エピソードレイヤーを介して、新しい会話アーカイブを同期します
2. 抽出 — LLM による事実の抽出（セマンティック）と、エンティティ／関係性の抽出（グラフ）を行います
3. 統合 — 埋め込みの類似度を用いるセマンティック統合器を介して、重複を排除し、マージし、競合を解決します
4. リフレクション — グラフリフレクションを介して、コミュニティ、橋渡しとなるエンティティ、時間的なパターンを検出します
5. 刈り込み — FSRS に着想を得た想起可能性スコアリング（セマンティック減衰）を用いて、価値の低い記憶を減衰させ、削除します

すべてのフェーズで _core インフラストラクチャを使用します。LLM 呼び出しには llm、永続化には db、類似度の計算には embeddings を使用します。

engram dream、Web UI の dream ボタン、または毎晩 02:00 に実行される scripts/install-daemon.sh（macOS では launchd、Linux では engram-dream.timer）／scripts/install-daemon.ps1（Windows タスク スケジューラ）から実行できます。

テクノロジー

コンポーネント	テクノロジー
ランタイム	Node.js ≥ 22（TypeScript）
データベース	SQLite + WAL モード（単一ファイル、ローカルファースト）
ベクトル検索	sqlite-vec
全文検索	SQLite FTS5（Porter ステミング）
埋め込み	@xenova/transformers 経由の nomic-embed-text
グラフ分析	graphology（Louvain コミュニティ、媒介中心性）
LLM プロバイダー	Anthropic、OpenRouter、Ollama（段階的カスケード）
MCP サーバー	@modelcontextprotocol/sdk
デーモン	launchd（macOS）、systemd ユーザータイマー（Linux）、タスク スケジューラ（Windows）— scripts/install-daemon.sh / .ps1

開発

npm run build        # TypeScript compilation
npm run test:run     # Run tests (vitest, 131 test files)
npm run mcp          # Start MCP server
npm run dev          # Dev CLI via tsx
npm run dream        # Run dream consolidation
npm run lint         # Type-check without emit

モデルキャッシュ

@xenova/transformers は、初回使用時に ONNX モデルの重みをダウンロードします（埋め込みの nomic-ai/nomic-embed-text-v1.5、リランカーの Xenova/bge-reranker-base、および 統合処理で使用する NLI モデル）。Engram はこれらを永続的なディレクトリに保存します。ディレクトリは次の順で決定されます。

1. ENGRAM_MODEL_CACHE_DIR — 任意の絶対パス（共有ネットワークボリュームも使用できます。読み取り専用の場合、ダウンロード済みモデルは使用できますが、新しいダウンロードは失敗します）
2. $HF_HOME/hub — HF_HOME が設定されている場合の、Hugging Face ハブキャッシュの場所
3. <data dir>/models — デフォルト：~/.local/share/engram/models （Windows では %LOCALAPPDATA%\engram\models）。engram.db と同じ場所にあります

ライブラリ独自のデフォルトである node_modules/@xenova/transformers/.cache/ は使用されません。すべての npm install、npm ci、グローバルアップグレードで消去されるためです。ここにキャッシュするビルドからアップグレードした場合、初回のモデル読み込み時（または engram init / engram migrate model-cache の実行時）に、重みが決定されたディレクトリに移動され、ログには1行だけ出力されます。再ダウンロードは発生しません。engram doctor は、使用中のディレクトリ、書き込み可能かどうか、durable: yes|no（no になるのは node_modules 内のパスを明示的に指定した場合のみ）、およびディレクトリの決定に使われた優先順位を表示します。engram update は models/ をバックアップしません。ロールバック時にキャッシュが見つからない場合は再ダウンロードされます。CI では ENGRAM_MODEL_CACHE_DIR にランナーの一時ディレクトリを指定し、実行間でそのディレクトリをキャッシュします。

設定

すべての設定は環境変数で行います。CLI と MCP サーバーは設定ファイルを読み込みません。例外は launchd の dream デーモンで、ランチャー（scripts/run-dream.sh）が ~/.config/engram/env を読み込むため、API キーを plist に記述せずに済みます。以下の変数はどれでもここに設定できます。

変数	デフォルト値	用途
ANTHROPIC_API_KEY	—	Anthropic プロバイダーを有効にします（LLM カスケードの最終ティア）
OPENROUTER_API_KEY	—	OpenRouter プロバイダーを有効にします
ENGRAM_OPENAI_BASE_URL	https://api.openai.com/v1	汎用の OpenAI 互換ルートです。OpenAI、LiteLLM ゲートウェイ（http://localhost:4000）、セルフホスト可能なサーバーに対応します。末尾がないオリジンには /v1 が追加されます
ENGRAM_OPENAI_MODEL	—	このルートで提供されるモデルです。設定すると openai ティアが有効になります
ENGRAM_OPENAI_API_KEY_ENV	OPENAI_API_KEY	ルートの認証情報を保持する環境変数の名前です。Engram は呼び出し時に値を読み取り、保存、表示、コミットすることはありません
ENGRAM_OPENAI_TEMPERATURE	—	設定されている場合にのみ送信されます。多くのゲートウェイや推論モデルでは temperature が拒否されるため、汎用ルートではデフォルトで省略されます
ENGRAM_LLM_PROVIDERS	ollama,openai,openrouter,anthropic	カンマ区切りのティア順です。省略したティアは試行されません。不明な名前は警告を出して無視されます
ENGRAM_LLM_TIMEOUT_MS	120000	すべてのティアに適用されるリクエストごとのタイムアウトです。低速なローカルモデルでは値を大きくしてください。Apple Silicon 上の 27B モデルでは、抽出プロンプトごとに 2〜4 分必要です。extraction smoke の予算もそれに合わせて増加します
OLLAMA_HOST	http://localhost:11434	Ollama のエンドポイントです。到達可能な場合、最初に使用されます
ENGRAM_LOCAL_MODEL	qwen2.5:7b	Ollama のモデル名です（Ollama ホストにプルしておく必要があります）
ENGRAM_LOCAL_MODEL_FALLBACKS	—	ENGRAM_LOCAL_MODEL がプルされていない場合に、順番に試行する Ollama モデルをカンマ区切りで指定します（例：llama3.1:8b,qwen3:8b）
ENGRAM_OPENROUTER_MODEL	google/gemini-2.5-flash-lite	OpenRouter のモデル名です
ENGRAM_DATA_DIR	プラットフォームのデフォルト値（下記参照）	データベース、アーカイブ、ログのルートディレクトリです
ENGRAM_DB_PATH	$ENGRAM_DATA_DIR/engram.db	SQLite データベースの場所です
ENGRAM_ARCHIVE_DIR	$ENGRAM_DATA_DIR/archive	会話アーカイブのディレクトリです
ENGRAM_LOGS_DIR	$ENGRAM_DATA_DIR/logs	ログディレクトリです
ENGRAM_CLAUDE_PROJECTS_DIR	~/.claude/projects	engram sync が Claude Code の会話を検索する場所です
ENGRAM_EMBEDDING_DIMS	256	Matryoshka 埋め込みの次元数です（既存の DB と一致している必要があります）
ENGRAM_RERANK_ENABLED	true	false または 0 に設定すると、クロスエンコーダーのリランキングを無効にします
ENGRAM_MODEL_CACHE_DIR	$ENGRAM_DATA_DIR/models（HF_HOME が設定されている場合は $HF_HOME/hub）	モデルの重みをダウンロード／キャッシュする場所です。node_modules 内には置かれません（モデルキャッシュを参照）
ENGRAM_SKIP_PREFLIGHT	—	1 に設定すると、npm install のプラットフォーム事前チェックを抑制します
ENGRAM_NO_UPDATE_CHECK	—	1 に設定すると、毎日の自動バージョン確認と「新しいバージョンが利用可能です」という通知を無効にします。engram update --check では引き続き確認されます（毎日のバージョン通知を参照）
ENGRAM_FORGET_RETENTION_DAYS	30	忘却したメモリを削除前に保持する日数です（想起対象外ですが、復元可能）。夢のプルーニングフェーズで完全削除されます。0 にすると次回実行時に消去されます。forget hard: true／engram memories delete --hard／purge --hard を指定すると、この設定は適用されません
ENGRAM_BIND	127.0.0.1	Web ビジュアライザーのバインドアドレスです（ネットワークに公開する場合は 0.0.0.0 を指定します。その場合、ENGRAM_WEB_TOKEN が必要です）
ENGRAM_WEB_TOKEN	ENGRAM_MCP_TOKEN	ビジュアライザーで必要なベアラートークン／?token= です（/api/health を除くすべてのルート）
ENGRAM_MCP_TOKEN	—	MCP デーモンの /mcp で必要なベアラートークンです。MCP サーバーを参照してください
ENGRAM_MCP_HOST	127.0.0.1	MCP デーモンのバインドアドレスです（ループバック以外を指定する場合は ENGRAM_MCP_TOKEN が必要です）
PORT	3001	Web ビジュアライザーのポートです
データディレクトリ。 ENGRAM_DATA_DIR が設定されていない場合、デフォルトは Linux/macOS では $XDG_DATA_HOME/engram、Windows では %LOCALAPPDATA%\engram です。この変数も未設定または空の場合、engram はすべてのプラットフォームで ~/.local/share/engram にフォールバックするため、既存のインストール先が移動することはありません（XDG_DATA_HOME が通常未設定の macOS でも、デフォルトは ~/.local/share/engram のままです）。CLI、MCP サーバー、dream デーモン、ウェブビジュアライザーのすべてのコンポーネントで、この共通ルールに従ってパスを解決します。

LLM プロバイダー。 抽出処理と dream パイプラインでは、既定で複数の階層を順に確認します。まず Ollama（OLLAMA_HOST に応答があり、ENGRAM_LOCAL_MODEL または ENGRAM_LOCAL_MODEL_FALLBACKS のいずれかのモデルがそこで取得されている場合。取得されていない場合はローカル階層をスキップし、そのホストで利用可能なモデルを列挙する警告を一度だけ表示します）、次に汎用の OpenAI 互換ルート（ENGRAM_OPENAI_MODEL が設定されている場合。OpenAI、LiteLLM などのゲートウェイ、セルフホストサーバーが対象で、認証情報は ENGRAM_OPENAI_API_KEY_ENV が指定する環境変数から読み取ります）、次に OpenRouter（OPENROUTER_API_KEY が設定されている場合）、最後に Anthropic（ANTHROPIC_API_KEY が設定されている場合）の順です。ENGRAM_LLM_PROVIDERS で階層の順序を変更したり、対象を限定したりできます（例：openai,anthropic）。engram doctor では、各階層の順序、エンドポイントとモデル、そのキーの参照元となる環境変数（キー自体は表示されません）、および Ollama 階層で解決されたローカルモデルを確認できます。

汎用ルートにおけるセキュリティ境界：Engram に渡すのは変数名であり、シークレットではありません。各デプロイ環境で、リポジトリ外の場所（シェルプロファイル、サービスの環境変数ファイル ~/.config/engram/env、ラッパー、またはスーパーバイザーの環境変数）で、各環境の認証情報をその変数に割り当てます。トークンが設定、ログ、--plan の出力に書き込まれることはありません。OpenRouter と汎用ルートは同じ OpenAI ワイヤークライアントを共有するため、リクエスト互換性に関する修正は両方に適用されます。 engram extract と engram dream には、少なくとも 1 つのプロバイダーを設定する必要があります。検索、remember、remember_batch、ウェブビジュアライザーには LLM は不要です。

参考資料

• SPEC.md — 要件とインターフェース契約を含むシステム仕様の全文
• CHANGELOG.md — 各バージョンのリリースノートとアップグレード手順
• docs/history/SPEC-legacy.md — 詳細な設計根拠を含む当初のビジョンドキュメント（アーカイブ済み）
• plans/ — 実装計画（フェーズ 1～4、フェーズ 6 の RLM、フェーズ 7 の拡張機能）
• decisions/ — アーキテクチャ決定記録