English version → engram-global

engram — AIエージェント用 人間型記憶基盤(MCPサーバー)

Claude Code / Codex / Antigravity(Gemini CLI)が共有する永続記憶。 使うほど思い出しやすくなり、使わない記憶は沈むが消えない — 人間の記憶と同じ性質を持つ。

---

クイックスタート(受け取った方へ)

方法1: 一発インストール

Windows(PowerShell):

irm https://raw.githubusercontent.com/ricoaiproject-cmd/engram/main/install.ps1 | iex

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/ricoaiproject-cmd/engram/main/install.sh | sh

これ1行で uv のインストール・engram のインストール・セットアップウィザードまで実行されます。 (macOS は git が必要です。無い場合は先に xcode-select --install を実行してください)

方法2: 3コマンドで手動インストール

Windows(PowerShell):

# 1. uv をインストール(既にある場合はスキップ)
irm https://astral.sh/uv/install.ps1 | iex

# 2. engram をインストール
uv tool install --python 3.12 git+https://github.com/ricoaiproject-cmd/engram.git

# 3. セットアップウィザードを実行
engram setup

macOS / Linux:

# 1. uv をインストール(既にある場合はスキップ)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. engram をインストール(uv 管理の Python を強制 — 下の注記参照)
UV_PYTHON_PREFERENCE=only-managed uv tool install --python 3.12 git+https://github.com/ricoaiproject-cmd/engram.git

# 3. セットアップウィザードを実行
engram setup

なぜ uv 管理の Python? engram は SQLite の拡張ロード(sqlite-vec が使用)に 対応した Python を必要とします。macOS 標準や python.org の Python は非対応で、 しかも存在すると uv はそちらを優先してしまうため、 UV_PYTHON_PREFERENCE=only-managed で uv 管理の Python を強制します (install.sh は自動で設定します)。engram doctor に確認項目があります。

セットアップウィザードが以下を自動で行います:

• 設定ファイル(~/.engram/config.toml)の作成
• 記憶フォルダの初期化
• 埋め込みモデルのダウンロード(初回のみ、約500MB)
• Claude Code / Codex / Antigravity への自動登録
• フック(自動符号化・自発的想起)の登録(Claude Code)

---

インストール後の使い方

エージェントに話しかけるだけ

engram のすべての操作はエージェントが自動的に行います。 ユーザーは普通に会話するだけで記憶が蓄積・活用されます。

最初にオンボーディングインタビューを受ける(推奨)

エージェントに次のように依頼してください:

~/.engram/ONBOARDING.md を読んで、私にインタビューして。

仕事の流儀・好み・背景情報を初期登録することで、すぐに記憶が活きはじめます。

環境の確認

engram doctor

Python バージョン・設定ファイル・モデルキャッシュ・埋め込み実行系(ONNX / torch)・ インストール健全性(pip 再インストール失敗の残骸 ~ngram 等による import 不能の検知)・ 各エージェントへの登録状況を [OK] / [NG] / [--] で一覧表示するほか、 FTS5(SQLite の全文検索拡張)が読み込めているか(欠けるとキーワード検索が 黙って劣化するため)と、data_dir/perf/perf_log.jsonl(下記)に記録された 直近の MCP ツール呼び出し・起動時間の要約行も表示します。 「なんとなく遅い」を勘ではなくデータで診断できます。

再セットアップ(新しいエージェントをインストールした後など)

engram setup

何度実行しても安全(冪等)です。未登録のエージェントだけが追加されます。

登録先のエージェントを選ぶ

複数のエージェントが入っていても、engram を繋ぎたいものだけを選べます。

# Claude Code だけに登録する
engram setup --agents claude

# Claude Code と Codex の両方に登録する
engram setup --agents claude,codex

有効な名前: claude / codex / gemini(antigravity は gemini の別名)。 --agents を省略した場合、対話モード(インタラクティブ)では検出されたエージェントが一覧表示され、番号で選べます。Enter を押すとすべてに登録されます。--non-interactive では従来どおり検出された全エージェントに自動登録されます。

ONNX による起動高速化(v0.6 の新機能)

一度だけ実行してください:

engram export-onnx

埋め込みモデルを ONNX に変換します(追加の依存は不要 — 変換はインストール済みの torch が一度だけ担当)。以後サーバーは自動的に ONNX を使い(embed_backend=auto)、 起動が 12〜24秒(torch import)から 約2秒 になります。MCP クライアント側の タイムアウト調整も不要になります。

安全装置: 変換時に torch 経路と ONNX 経路で同じサンプル文(ModernBERT の スライディングウィンドウ境界を越える長文を含む)を埋め込み、コサイン類似の 最小値が 0.999 を下回るモデルはインストールを拒否します — 分布がずれた 埋め込み空間を黙って採用すると、既存の index.db に対する recall が静かに 壊れるためです。

config.toml の embed_backend(または環境変数 ENGRAM_EMBED_BACKEND)で 実行系を選べます: auto(既定。ONNX 生成済みならそれを使い、無ければ torch)/ onnx(強制。未生成ならエラー)/ torch(フォールバックを強制)。

起動モード(ENGRAM_PRELOAD)

既定は auto です(v0.10.0〜): ONNX モデルが生成済みなら background (ハンドシェイク即応答)、torch フォールバック環境なら blocking を自動選択 するため、通常は調整不要です。MCP の起動タイムアウト設定が効かないクライアント (実例: Codex Desktop 26.707)でもそのまま接続できます。

値	挙動
auto(既定)	ONNX 生成済みなら background、無ければ blocking。
blocking	ハンドシェイク前にメインスレッドでモデルを読み込む。接続後の recall は常に即応答。torch 経路では warm 12〜24秒 / cold 50秒超かかるため、クライアント側の MCP 起動タイムアウトを120秒以上に延長すること(Claude Code なら MCP_TIMEOUT=120000)。
background	ハンドシェイクに即応答し、モデルは裏スレッドで読み込む。ONNX 経路では安全(初回ツールが読み込み完了を数秒待つだけ。実測: 別スレッドでも約5秒)。torch 経路では非推奨: Windows では asyncio イベントループ稼働中の別スレ