engram-cc

Engram Context Continuum

あらゆる AI セッションに対応するメモリ基盤です。 インストールは一度だけ。あらゆる AI コーディングアシスタントで使えます。セッションをまたいでも、フォルダー名を変更しても、ツールを切り替えても、コンテキストを保持します。

神経科学において、エングラムとは記憶が脳に残す物理的な痕跡です。EngramCC は AI に対して同じ役割を果たします。AI アシスタントが学習し、決定し、実行した内容を保持するローカルメモリ基盤となり、次のセッションを前回の続きから正確に始められます。

---

課題

AI コーディングセッションは毎回、ゼロから始まります。アシスタントは昨日読んだファイルを読み直し、すでに知っている規約を学び直し、すでに回答した質問を再び尋ねます。コンテキストの圧縮によって、作業中のセッションが気付かないうちに消去されます。ツールを切り替えると、メモリはすべて失われます。

EngramCC は、プロンプトを工夫するのではなく、あらゆる AI アシスタントの下で動作する永続メモリ層を構築することで、インフラストラクチャのレベルからこの問題を解決します。

---

クイックインストール

npx engram-cc

ECC に管理させるプロジェクトのルートディレクトリから実行するか、--project-dir <path> を指定してください。

セットアップ CLI はハードウェアを検出し、プロジェクト内に .engram-cc/ ワークスペースを用意し、共有モデルディレクトリを尋ねたうえで、.engram-cc/assistant-configs/ にアシスタントのフック／MCP 設定スニペットを生成します。ユーザーホームの設定は変更しません。

標準 MCP インストールコマンド

npm から MCP サーバーを自動インストールするアシスタント向けの、EngramCC の標準コマンドは次のとおりです。

npx --yes --package=@morous-dev/engram-cc -- engramcc-mcp

同等の npm exec 形式：

npm exec --yes --package=@morous-dev/engram-cc -- engramcc-mcp

アシスタントは npx @morous-dev/engram-cc mcp を推測して使わないでください。上記の明示的なパッケージ／実行ファイル形式を使用してください。

プロジェクト内に ECC をセットアップする場合、.engram-cc/assistant-configs/ に生成されるスニペットでは、意図的に代わりに node <project-local build/mcp/server.js> を使用します。上記の npx --package ... 形式は、プロジェクト内のセットアップを先に実行せずに、npm から EngramCC を直接インストールするアシスタント向けです。

---

対応アシスタント

アシスタント	フックのサポート	MCP のサポート
Claude Code	ライフサイクルフック全般	recall / search / recent / graph_query
Gemini CLI	ライフサイクルフック全般	recall / search / recent / graph_query
VS Code Copilot	—	recall / search / recent / graph_query
Codex CLI	ネイティブフック（session_start、pre_tool_use、stop）＋トランスクリプト完全一致の user_prompt_submit / post_tool_use ＋合成された pre_compact	recall / search / recent / graph_query
Kilo CLI	ラッパーによるサポートのみ。ネイティブフックは未検証	recall / search / recent / graph_query
OpenCode	ライフサイクルフック全般	recall / search / recent / graph_query
Cursor	—	recall / search / recent / graph_query

Windows では、生成されるフックスニペットは src/hooks/hook-runner.mjs を呼び出します。これにより、壊れやすい cmd /C の引用符処理に頼らず、アシスタントとプロジェクトの環境変数が注入されます。

Codex 固有の注意：プロンプト／ツールの正確なブリッジは、Codex 独自のセッション JSONL を CODEX_HOME / ~/.codex/sessions/ の下から読み取りますが、ECC が状態を書き込むのは引き続きプロジェクト内の .engram-cc/ ディレクトリのみです。Codex は実際のプロンプト送信時の注入フックを公開していないため、起動時のコンテキストには Codex のターンポリシーも含まれます。このポリシーは、それ以前のコンテキストが圧縮によって失われた可能性がある場合に、ユーザーのターンで EngramCC MCP メモリを使うようアシスタントを誘導します。

Kilo 固有の注意：現在確認済みのサポートは、MCP と、セッション開始／セッション終了時の継続性を実現する ekilo ラッパーフローです。Kilo ではネイティブのライフサイクルフックが要望として提出されている段階のため、ECC はまだ Kilo のネイティブフックとの同等性を謳っていません。

---

仕組み

EngramCC は セッションミドルウェア として動作します。ライフサイクルフックがセッション中の出来事を記録し、ローカル SLM がセッション終了時にオフラインでメモリを合成し、MCP サーバーが事前に整理したコンテキストを、接続されたあらゆるアシスタントに提供します。

┌─────────────────────────────────────────────────────────────────┐
│                    Your AI Coding Session                        │
│                                                                   │
│  UserPromptSubmit → PostToolUse → PreCompact → Stop              │
│         │               │              │          │               │
│         └───────────────┴──────────────┴──────────┘              │
│                                 │                                 │
│                         SQLite event DB                           │
│                                 │                                 │
│                     ┌───────────┴───────────┐                    │
│                     │   Local SLM Archivist  │                    │
│                     │  (no API calls, 100%   │                    │
│                     │   offline synthesis)   │                    │
│                     └───────────┬───────────┘                    │
│                                 │                                 │
│              ┌──────────────────┼──────────────────┐             │
│              │                  │                  │             │
│         YAML handoff     Knowledge graph     Vector store        │
│         (hot resume)      (BFS traversal)   (semantic search)    │
│              │                  │                  │             │
│              └──────────────────┴──────────────────┘             │
│                                 │                                 │
│                         MCP server                                │
│                    (recall / search / recent                      │
│                       / graph_query)                              │
└─────────────────────────────────────────────────────────────────┘
         ↑                                         ↓
   SessionStart hook                       Next session
   injects context                         picks up here

セッションのライフサイクル

フック	実行タイミング	動作
UserPromptSubmit	ユーザーがメッセージを送信したとき	意図と判断のシグナルを取得します
PostToolUse	任意のツールの処理が完了したとき	ファイル操作、エラー、ツールの結果を取得します
PreCompact	コンテキストが上限に近づいたとき	消去前にセッション状態をスナップショットします
SessionStart	セッションを開始したとき	ホットハンドオフ、またはコールドサマリーと MCP ポインターを注入します
Stop	セッションを終了したとき	SLM による統合 → ハンドオフ YAML、グラフ、ベクトルストア

階層型コンテキスト注入

EngramCC はコンテキストを無差別に注入せず、必要な箇所に絞って注入します。

• ホット再開（前回のセッションから 30 分未満）：ハンドオフ XML 全体を注入します。作業コンテキスト、判断、変更したファイル、エラーをすべて含みます
• コールドスタート：1 文の見出しと MCP recall ツールへのポインターを表示します。古くなったコンテキストによるトークンの無駄をなくします

メモリアーキテクチャ

レイヤー	ストレージ	内容	有効期間
作業	YAML	設定、規約、永続的な判断	セッションをまたいで保持
エピソード	SQLite + FTS5	すべてのセッションイベント。全文検索可能	プロジェクト単位
セマンティック	SQLite グラフ	ファイルと判断のナレッジグラフ、BFS による探索	プロジェクト単位
手続き	sqlite-vec	埋め込みインデックス付きの重要度の高いイベント	プロジェクト単位

---

ローカル SLM パイプライン

EngramCC はまずローカルモデルを使ってセッションメモリを統合します。圧縮、ハンドオフ、検索のサポートに外部 API 呼び出しを一切必要としません。

セットアップ CLI はハードウェアを検出し、利用可能な最適なティアを選択します。

ティア	モデル	必要な RAM	動作
1	ルールベース	0	常時稼働するヒューリスティック抽出
2	MiniLM-L6-v2 ONNX	~400 MB	@huggingface/transformers による埋め込み
3	Llama 3.2 3B Q5_K_M	~4 GB	主となるローカル統合ティア
3b	Qwen3.5 4B Q4_K_M	~3.5 GB	多言語およびコーディング性能に優れた、別の統合ティア
3c	Gemma 3 4B QAT Q4_0	~3 GB	構造化推論に優れた、別の統合ティア
4	Ollama / LM Studio / Groq	ユーザー指定	外部 HTTP プロバイダー

モデルは engramcc のセットアップ時に選択した共有ディレクトリに保存され、<projectDir>/.engram-cc/config.json に記録されます。ティアは自動的に切り替わります。ティア 3 のモデルが利用できない場合はティア 2 が実行され、ティア 2 が利用できない場合はティア 1 が実行されます。コアとなるメモリ取得が妨げられることはありません。

---

安定したプロジェクト ID

EngramCC はフォルダーパスではなく、.ecc-id に保存された安定した UUIDでプロジェクトを追跡します。つまり、次のようになります。

• プロジェクトフォルダーの名前を変更しても、履歴は保持されます
• 別のドライブに移動しても、履歴は保持されます
• git から再クローンしても、履歴は保持されます（git のルートコミットハッシュにフォールバックします）

解決順序：.ecc-id ファイル → git のルートコミットハッシュ → 新しい UUIDv4（一度だけ書き込まれ、再生成されることはありません）。

---

データの保存場所

<projectDir>/.engram-cc/
├── sessions/
│   └── <uuid>.db               ← SQLite DB per project (all memory tiers)
├── assistant-configs/          ← Local hook/MCP snippets per assistant
├── config.json                 ← Project config, including shared models path
├── handoff.yaml                ← Session handoff (hot resume data)
└── working.yaml                ← Cross-session working memory

<chosenModelsRoot>/Engram Context Continuum/models/
└── <model>.gguf                ← Shared GGUF models reused across projects

すべてのデータはローカルに保存されます。コア機能の動作にネットワーク呼び出しはありません。認証情報、トークン、API キーも不要です。

---

MCP ツール

MCP 経由で接続すると、任意のアシスタントから EngramCC に直接クエリできます。

ツール	目的
recall	セッションコンテキスト全体：ハンドオフ + 作業メモリ
search	すべてのセッションイベントを対象とした FTS5 全文検索
recent	最新の N 件のイベント。カテゴリで絞り込み可能
graph_query	ナレッジグラフの BFS 探索

---

設定

plugin-config.yaml で圧縮ティアまたは外部プロバイダーを上書きできます。

# Force a specific compression tier (default: auto)
compression:
  tier: "tier3b"

  # Tier 4 only
  external:
    provider: "ollama"
    model: "phi4-mini"
    base_url: "http://localhost:11434"

---

ベンチマーク

以下の数値は、引き継ぎ圧縮の修正後、2026 年 3 月 14 日に現在のリポジトリの状態を対象として検証したものです。過去の最高記録ではなく、実際に実行した結果を示しています。

検証済みベンチマーク実行結果

コマンド	測定内容	現在の結果
npm run build	TypeScript のコンパイル整合性	✅ PASS
node benchmark/test-session-db.mjs	セッション DB、アーカイブ、再開チェーン、引き継ぎのリグレッション	✅ 53/53
npm run test:quality	S1/S2/S3 にわたるエンドツーエンドの引き継ぎ品質	✅ 20/20
node benchmark/test-hook-portability.mjs	アシスタント間のフック環境と起動の移植性	✅ 14/14
node benchmark/test-codex-adapter.mjs	Codex のトランスクリプト同期＋トリガー＋停止のリグレッション	✅ 29/29
npm run test:brutal:quick	実データ抽出のキャリブレーション（WildChat + SWE-bench）	✅ PASS
npm run test:lifecycle:quick	100 サイクルの実データライフサイクル／アーカイブ保持の観測	✅ PASS
node benchmark/test-adversarial.mjs --model llama3.2-3b	敵対的な SLM 入力 A1–A11	✅ 11/11
node benchmark/test-adversarial.mjs --model qwen	敵対的な SLM 入力 A1–A11	✅ 11/11
node benchmark/test-adversarial.mjs --model gemma3-4b	敵対的な SLM 入力 A1–A11	✅ 11/11
node benchmark/test-tier-comparison.mjs	ティア間の圧縮保持（4→20 サイクル）	✅ tier3、tier3b、tier3c で 38/38
node benchmark/test-scale.mjs	プロンプト長の安定性	✅ Llama 16/16 · Qwen 15/16
node benchmark/test-compaction-marathon.mjs	複数回の圧縮におけるメモリ保持	✅ 53/53
node benchmark/test-diffmode.mjs	文法制約付き JSON 出力	✅ Llama 3.2 3B + Qwen3.5 4B で PASS

これらの結果が示すもの

引き継ぎ品質

npm run test:quality は、セッションイベントから次のセッションへのコンテキスト注入までの全経路をテストします。

シナリオ	アサーション	結果
S1 — 初期セッション	6/6	✅
S2 — ホット再開	5/5	✅
S3 — マラソン／コールドスタート	9/9	✅

合計：20/20

実データの検索／保持

npm run test:brutal:quick と npm run test:lifecycle:quick は、公開されている外部データセットを使用します：

• WildChat-1M のコーディング会話
• SWE-bench の GitHub issue 記述

現在検証済みの観測結果：

• 抽出の過酷なキャリブレーション：PASS
• 敵対的な抽出器トラップ：15/15
• チェーンフェーズ extract → store → search → snapshot：PASS
• ライフサイクルのチェックポイント：サイクル 25 / 50 / 75 / 100 における FTS5 再現率は 100% / 80% / 80% / 100%
• サイクル 100 のソース別再現率：WildChat 5/7 (71%)、SWE-bench 13/13 (100%)

ライフサイクル実行での 2 件の取りこぼしは、アーカイブの破損ではなく、信号の弱い用語（nothing、creator）でした。

SLM の敵対的堅牢性

敵対的テストスイートは、このリポジトリで最も難しい精度ベンチマークです。コードの壁、スタックトレース、多言語セッション、エラーの反転、専門分野の用語、埋もれた現在のタスク、複数回の圧縮チェーンを対象とします。

現在検証済みのスコア：

モデル	スコア
Llama 3.2 3B Q5_K_M	11/11
Qwen3.5 4B Q4_K_M	11/11
Gemma 3 4B QAT Q4_0	11/11

これは、A11 が以前は実際の課題だったため重要です。圧縮チェーンに決定論的な引き継ぎ状態を追加したことで、現在は合格しています。

SLM のスケール安定性

node benchmark/test-scale.mjs は、プロンプトの長さを 128 語から 985 語まで増やして検証します。

モデル	結果
Llama 3.2 3B	16/16
Qwen3.5 4B	15/16

現在の注意点：

• Qwen 4B は S4（985 語）の幻覚なしチェックで 1 件取りこぼしました。

ティア間の圧縮保持

node benchmark/test-tier-comparison.mjs は、3 つすべての本番用 GGUF ティアで同じ 4→20 サイクルの圧縮ストレステストを実行します。

ティア	結果
tier3 — Llama 3.2 3B	38/38
tier3b — Qwen3.5 4B	38/38
tier3c — Gemma 3 4B	38/38

この README の更新時点で、raw snapshot と比較した検証済みのトークン削減率は次のとおりです：

• tier3：24–26%
• tier3b：16–23%
• tier3c：20–28%

マルチコンパクションマラソン

node benchmark/test-compaction-marathon.mjs は、4、8、12、16、20 回のコンパクションサイクルにわたる長時間セッションをシミュレートします。

現在確認済みの結果：

• 53/53 件のアサーションに合格
• すべてのアンカーファクトが 20 回のコンパクションサイクルを経ても保持されました

重要な注意事項

• tier3 は、一部の実行で文法制約付きの差分モードから文章形式に戻ることがあります。上記の検証済みスイートでは正確性は問題ありませんでしたが、このフォールバックはまだ発生します。
• Qwen 4B は全般的に高い性能を発揮しますが、現在のスケールテストの結果は 15/16 で、満点ではありません。
• 以前の A11 の失敗は現在の状態ではなく、現時点での弱点として挙げるべきではありません。
• benchmark/test-160k-real.mjs は 引き継ぎパッチ適用後に再実行されていないため、以前の数値はここでの主要な主張から意図的に省いています。

総合評価

ECC は、CLI のメモリ基盤として最も重要な領域で、現在優れた性能を発揮しています。

• 実データの抽出と保持
• エンドツーエンドの引き継ぎ品質
• 連鎖するコンパクションの継続性
• ティアをまたいだ SLM の堅牢性

検索レイヤーは、長期的なセーフティネットとして引き続き機能します。SLM レイヤーは、以前の A11 の崩壊を起こさずに、コンパクションをまたいでセッション状態を引き継ぐのに十分な性能を備えました。

---

開発

npm run build       # Compile TypeScript → build/
npm run typecheck   # Type check without emit
npm run clean       # Remove build/
npm run setup       # Build + run setup CLI

ランタイム要件：

• Node.js >= 18（すべてのフック、MCP サーバー、セットアップ CLI）

コントリビューター向けの注意：

• アシスタントアダプターの追加や変更を行う前に、ADAPTER-AUTHORING.md を確認してください。変更可能な箇所、機能ルール、ストレージルール、現在の移植性の境界について説明しています。

---

プラットフォームサポート

EngramCC は Windows、macOS、Linux（x64 および ARM64）で動作します。

依存関係	種類	プラットフォームの対応状況
better-sqlite3	ネイティブ C++ アドオン	主要なすべてのプラットフォームと Node バージョン向けのビルド済みバイナリ
node-llama-cpp (Tier 3)	ネイティブアドオン	13 種類のビルド済みバリアント：Windows/macOS/Linux × x64/ARM64 × CPU/CUDA/Vulkan/Metal
sqlite-vec (Vector store)	ネイティブアドオン	Windows x64、macOS x64/ARM64、Linux x64/ARM64 向けにビルド済み
@huggingface/transformers (Tier 2)	純粋な JS + WASM	汎用 — ネイティブコード不要
その他すべての依存関係	純粋な JS	汎用

トラブルシューティング：better-sqlite3 のビルド失敗

better-sqlite3 は、ネイティブコンパイルが必要な唯一の必須依存関係です。一般的なプラットフォームと Node バージョンの組み合わせ向けに、ビルド済みバイナリを提供しています。環境に適合するビルド済みバイナリがない場合、npm はソースからのコンパイルに切り替えます。そのためには、次のものが必要です。

Windows：

npm install --global windows-build-tools
# or install Visual Studio Build Tools with "Desktop development with C++"

macOS：

xcode-select --install

Linux (Debian/Ubuntu)：

sudo apt install build-essential python3

Linux (Fedora/RHEL)：

sudo dnf groupinstall "Development Tools"

npm install が gyp ERR! または node-pre-gyp のエラーで失敗する場合は、上記のビルドツールをインストールしてから npm install を再実行すれば解決します。

トラブルシューティング：ローカル SLM ティアを利用できない

ローカルの合成ティアには、プロジェクト用に設定された共有モデルディレクトリ内の GGUF モデルが必要です。サポート対象の Tier 3 モデルが見つからない場合、EngramCC は Tier 2（埋め込み）または Tier 1（ルールベース）にフォールバックします。

例：

engramcc --tier=tier3 --project-dir <project> --models-dir <shared-models-dir>
engramcc --tier=tier3b --project-dir <project> --models-dir <shared-models-dir>
engramcc --tier=tier3c --project-dir <project> --models-dir <shared-models-dir>

おおよそのランタイム要件：

• tier3 Llama 3.2 3B：約 4 GB の RAM
• tier3b Qwen3.5 4B：約 3.5 GB の RAM
• tier3c Gemma 3 4B：約 3 GB の RAM

トラブルシューティング：ベクトルストアが有効にならない

ベクトルストアは、オプションの依存関係である sqlite-vec を使用します。読み込みに失敗しても、EngramCC はベクトル検索なしで通常どおり動作し、他のすべてのメモリティア（エピソード記憶、意味記憶、作業記憶）には影響しません。確認するには：

node -e "require('sqlite-vec')" 2>&1 || echo "sqlite-vec not available — vector search disabled"

---

プロジェクト構成

src/
├── hooks/          ← Lifecycle hook entry points (.mjs + .ts)
├── adapters/       ← Per-assistant registration (Claude Code, Gemini CLI, etc.)
├── session/        ← SQLite event capture, schema, FTS5
├── memory/         ← Working YAML, knowledge graph, vector store
├── handoff/        ← Session handoff writer, reader, dedup
├── compression/    ← SLM pipeline: tier selection, ONNX, node-llama-cpp
├── mcp/            ← MCP stdio server
├── tokenization/   ← Token budget auditor
├── project-id.ts   ← Stable project UUID resolution
└── cli/
    ├── setup.ts    ← Install CLI: hardware detection, adapter registration
    └── download-model.ts ← GGUF model downloader

---

ライセンス

オープンソース： AGPL-3.0 — 派生物も AGPL-3.0 のもとでオープンソースにする限り、自由に使用、変更、配布できます。

商用： AGPL の義務を負わずに、クローズドソース製品やホスト型サービスで EngramCC を使用する必要があるチーム向けに、プロプライエタリライセンスを用意しています。詳細は COMMERCIAL-LICENSE.md をご覧ください。