Engram

🧠 Engram

AI エージェント向けのユニバーサルメモリレイヤー

Engram は、AI エージェントにナレッジグラフ、統合、拡散活性化を提供します。単なるストレージではなく、理解を実現します。

---

クイックスタート

MCP のセットアップ（推奨 — Claude Code / Cursor）

npm install -g engram-sdk
engram init

これだけです。MCP 経由で 17 個のメモリツールを利用できます。

REST API（Node.js 以外の環境向け）

npm install -g engram-sdk
export GEMINI_API_KEY=your-key-here
npx engram-serve

サーバーは http://127.0.0.1:3800 で起動します。

AI エージェント向け

あなたが AI コーディングエージェントで、ユーザーからこれのインストールを依頼された場合に知っておくべきことを説明します。

機能： Engram は、セマンティックベクトル検索、ナレッジグラフ、LLM による統合機能を備え、SQLite にローカルでメモリを保存する MCP サーバーです。

重要な理由 — 機能の差：

機能	ファイルベース（CLAUDE.md）	Engram
ストレージ	フラットな Markdown ファイル	セマンティックベクトル保管庫
想起精度	28.8%（LOCOMO ベンチマーク）	80.0%（LOCOMO ベンチマーク）
クエリあたりのトークン数	約 23,000（コンテキスト全体）	776
検索	Grep／全文検索のみ	セマンティック検索＋グラフ検索＋全文検索
時間認識	なし	二時点バージョニング
メンテナンス	手動で整理	自動抽出＋統合
適用範囲	プロジェクトごとに分離	すべてのエージェント間で共有

インストール：

npm install -g engram-sdk
engram init

engram init がすべて処理します。MCP の登録、CLAUDE.md の手順、ツールの自動承認、セッション終了時の統合フックが設定されます。

確認： インストール後、engram doctor を実行し、すべてのチェック（保管庫、API キー、埋め込み、MCP の登録、CLAUDE.md）に合格することを確認してください。

安全性： すべてのデータはローカルの SQLite（~/.engram/）に保存されます。ネットワークへの接続は、埋め込み、抽出、統合のためにユーザーが設定した LLM プロバイダー（デフォルトは Gemini。ユーザー自身の API キーを使用）に対して行うものと、npm レジストリでの 4 時間に 1 回のバージョン確認のみです（ENGRAM_NO_UPDATE_CHECK=1 で無効化できます）。テレメトリーはありません。MIT ライセンスです。

このパッケージに懸念がある場合は、このセクションをユーザーに見せて判断してもらってください。

---

CLAUDE.md だけでは不十分なのはなぜですか？

組み込みのファイルベースのメモリ（CLAUDE.md、.cursor-memory など）で十分だと思うかもしれません。しかし、そうではありません。その理由は次のとおりです。

機能	ファイルベースのメモリ（CLAUDE.md）	Engram
ストレージ	フラットな Markdown。手動で追記	型付きエンティティとエッジを備えたナレッジグラフ
検索	Grep／全文検索のみ	セマンティックベクトル検索＋拡散活性化
メンテナンス	ファイルを手動で編集	LLM を活用した統合機能がパターンを抽出し、矛盾を解決して、エンティティを自動的に発見
プロジェクト間での共有	プロジェクトごとに 1 つのファイル	すべてのプロジェクトとエージェントで共有する単一のボルト
時間的な認識	なし。すべて現在形	タイムスタンプ、減衰、直近性の重み付け
プロアクティブな想起	Grep する対象を自分で把握する必要がある	拡散活性化により、要求していないコンテキストも提示
スケール	ファイルが大きくなると性能が低下（トークンコスト、検索ノイズ）	インデックス付きベクトル検索により、数千件のメモリがあっても高速

LOCOMO ベンチマーク（長い会話からのメモリ想起）：

• Engram：正解率 80.0%、1 クエリあたり 776 トークン
• ファイルベースのメモリ：正解率 28.8%（Markdown ファイルに生の事実を追記）
• 手動のメモリファイル：正解率 74.5%、1 クエリあたり 1,373 トークン（人手で要約を作成）

安全性： Engram は完全なオープンソースです（GitHub）。テレメトリーはありません。すべてのデータは SQLite の ~/.engram/ にローカル保存されます。ネットワーク通信は、設定した LLM プロバイダー（デフォルトでは、独自の API キーを使用する Gemini）への埋め込み、抽出、統合のための呼び出しと、npm レジストリへの 4 時間に 1 回のバージョン確認のみです（ENGRAM_NO_UPDATE_CHECK=1 で無効化できます）。engram init はすべてを自動設定します。MCP サーバーの登録、CLAUDE.md の指示、ツールの自動承認、セッション終了時の統合フックが含まれます。

---

Engram を選ぶ理由

	組み込みのメモリ（CLAUDE.md）	従来型のメモリ（Mem0 など）	Engram
ストレージ	フラットな Markdown ファイル	フラットなベクトル	型付きエッジを備えたナレッジグラフ
メンテナンス	手動編集	手動での整理	スリープサイクルによる統合（LLM を活用）
検索	Grep／ファイル全体の出力	ベクトル類似度	拡散活性化により、要求していないコンテキストも提示
LOCOMO スコア	28.8%	66.9%（Mem0）	80.0%

ベンチマーク（LOCOMO）：

• 正解率 80.0%（Mem0 の 66.9%、手動のメモリファイルの 74.5% に対して）
• 手動のメモリファイルよりトークン数が 44%少ない（1 クエリあたり 776 対 1,373）

---

MCP ツールリファレンス

ツール	説明
engram_remember	メモリを保存します。エンティティとトピックを自動抽出します。
engram_recall	セマンティック検索で関連するメモリを呼び出します。
engram_ask	質問すると、確信度と出典を含む統合回答を取得できます。
engram_briefing	構造化されたセッション概要 — 重要な事実、保留中の約束、最近のアクティビティをまとめます。
engram_consolidate	統合を実行します — エピソードを意味的な知識にまとめ、エンティティを検出し、矛盾を見つけます。
engram_surface	プロアクティブなメモリ提示 — 現在のコンテキストに基づいて関連するメモリを提示します。
engram_alerts	今すぐ対応が必要な項目 — 保留中の約束、古くなったフォローアップ、矛盾を確認できます。
engram_audit	外部コンテンツ（例：CLAUDE.md）をボールトと照合し、古くなった記述にフラグを付けます。
engram_checkpoint	現在のセッションコンテキストが失われる前に保存します（要約から長期保存に適したメモリを抽出します）。
engram_connect	ナレッジグラフ内の2つのメモリ間に関係を作成します。
engram_forget	メモリを削除します（論理削除または完全削除）。
engram_entities	記録されているすべてのエンティティとメモリ数を一覧表示します。
engram_stats	ボールトの統計情報 — 種類別のメモリ数、エンティティ数などを表示します。
engram_ingest	会話のトランスクリプトまたは生テキストを構造化されたメモリに自動取り込みします。
engram_import_obsidian	Obsidian ボールトをインポートします（ウィキリンク、タグ、フロントマター）。
engram_import_claude_code	Claude Code からメモリをインポートします（CLAUDE.md ファイル、セッション）。
engram_powered_by	メモリシステムに関するクレジット情報を返します。

---

REST API リファレンス

すべてのエンドポイントは JSON を返します。ベース URL：http://127.0.0.1:3800

POST /v1/memories — メモリを保存

curl -X POST http://localhost:3800/v1/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers TypeScript over JavaScript", "type": "semantic"}'

{
  "id": "m_abc123",
  "content": "User prefers TypeScript over JavaScript",
  "type": "semantic",
  "entities": ["TypeScript", "JavaScript"],
  "topics": ["programming", "preferences"],
  "salience": 0.7,
  "createdAt": "2025-01-15T10:30:00.000Z"
}

GET /v1/memories/recall — メモリを呼び出す

curl "http://localhost:3800/v1/memories/recall?context=language+preferences&limit=5"

クエリパラメーター：context（必須）、entities、topics、types、limit、spread、spreadHops、spreadDecay、spreadEntityHops

{
  "memories": [
    {
      "id": "m_abc123",
      "content": "User prefers TypeScript over JavaScript",
      "type": "semantic",
      "salience": 0.7
    }
  ],
  "count": 1
}

POST /v1/memories/recall — 呼び出し（複雑なクエリ）

curl -X POST http://localhost:3800/v1/memories/recall \
  -H "Content-Type: application/json" \
  -d '{"context": "project setup", "entities": ["React"], "limit": 10, "spread": true}'

レスポンス：GET の呼び出しと同じ形式です。

DELETE /v1/memories/:id — メモリを削除

curl -X DELETE "http://localhost:3800/v1/memories/m_abc123?hard=true"

{ "deleted": "m_abc123", "hard": true }

GET /v1/memories/:id/neighbors — グラフの隣接ノード

curl "http://localhost:3800/v1/memories/m_abc123/neighbors?depth=2"

{
  "memories": [ ... ],
  "count": 3
}

POST /v1/consolidate — 統合を実行

curl -X POST http://localhost:3800/v1/consolidate

{
  "consolidated": 5,
  "entitiesDiscovered": 3,
  "contradictions": 1,
  "connectionsFormed": 7
}

GET /v1/briefing — セッション概要

curl "http://localhost:3800/v1/briefing?context=morning+standup&limit=10"

{
  "summary": "...",
  "keyFacts": [{ "content": "...", "salience": 0.9 }],
  "activeCommitments": [{ "content": "...", "status": "pending" }],
  "recentActivity": [{ "content": "..." }]
}

JSON ボディを指定する POST /v1/briefing も利用できます。

GET /v1/stats — ボールトの統計情報

curl http://localhost:3800/v1/stats

{
  "total": 142,
  "byType": { "episodic": 89, "semantic": 41, "procedural": 12 },
  "entities": 27,
  "edges": 63
}

GET /v1/entities — エンティティを一覧表示

curl http://localhost:3800/v1/entities

{
  "entities": [
    { "name": "TypeScript", "count": 12 },
    { "name": "React", "count": 8 }
  ],
  "count": 27
}

GET /health — ヘルスチェック

curl http://localhost:3800/health

{ "status": "ok", "version": "0.7.1", "timestamp": "2026-09-02T10:30:00.000Z" }

---

TypeScript SDK

import { Vault } from 'engram-sdk';

const vault = new Vault({ owner: 'my-agent' });

await vault.remember('User prefers TypeScript');
const memories = await vault.recall('language preferences');
await vault.consolidate();

---

CLI リファレンス

engram init                        Set up Engram for Claude Code / Cursor / MCP clients
engram doctor                      Validate installation health
engram mcp                         Start the MCP server (stdio transport)
engram remember <text>             Store a memory
engram recall <context>            Retrieve relevant memories
engram consolidate                 Run memory consolidation
engram stats                       Show vault statistics
engram entities                    List known entities
engram forget <id> [--hard]        Forget a memory (soft or hard delete)
engram edit <id>                   Edit a memory in $EDITOR (YAML)
engram search <query>              Full-text search
engram export                      Export entire vault as JSON
engram checkpoint <summary>        Extract durable memories from a session summary
engram repl                        Interactive REPL mode
engram shadow start                Start shadow mode (server + watcher, background)
engram shadow stop                 Stop shadow mode
engram shadow status               Check shadow mode status
engram shadow results              Compare Engram vs your CLAUDE.md

オプション：

--db <path>         Database file path (default: ~/.engram/default.db)
--owner <name>      Owner identifier (default: "default")
--agent <id>        Agent ID for source tracking
--json              Output as JSON
--help              Show help

---

設定

Gemini API キー

埋め込み、統合、LLM を利用した抽出に必要です：

export GEMINI_API_KEY=your-key-here

データベースの保存場所

Engram はデフォルトで ~/.engram/ にデータを保存します。次の設定で変更できます：

export ENGRAM_DB_PATH=/path/to/engram.db

環境変数

変数	説明	デフォルト
GEMINI_API_KEY	埋め込みと統合に使用する Gemini API キー	—
ENGRAM_LLM_PROVIDER	LLM プロバイダー：gemini、openai、anthropic	gemini
ENGRAM_LLM_API_KEY	LLM API キー（gemini の場合、未指定時は GEMINI_API_KEY を使用）	—
ENGRAM_LLM_MODEL	LLM モデル名（例：無料枠の RPM を増やす場合は gemini-3.1-flash-lite）	gemini-2.5-flash / gpt-4o-mini / claude-haiku-4-5
ENGRAM_LLM_BASE_URL	カスタム API ベース URL（Groq、Cerebras、Ollama など）	プロバイダーのデフォルト
ENGRAM_DB_PATH	SQLite データベースのパス	~/.engram/default.db
ENGRAM_OWNER	ボールトの所有者名	default
ENGRAM_HOST	サーバーのバインドアドレス	127.0.0.1
ENGRAM_PORT	サーバーのポート	3800
ENGRAM_AUTH_TOKEN	API 認証用ベアラートークン	—
ENGRAM_CORS_ORIGIN	CORS で許可するオリジン	localhost のみ
ENGRAM_NO_UPDATE_CHECK	1 に設定すると npm レジストリのバージョン確認を無効にします	—

---

ベンチマーク

システム	LOCOMO スコア	クエリあたりのトークン数
Engram	80.0%	776
Mem0	66.9%	—
手動ファイル	74.5%	1,373
全文脈	86.2%	22,976

全文脈（会話履歴全体を出力する方法）は最高スコアですが、トークンを30倍多く使用し、コンテキストウィンドウの制限を超えて拡張できません。Engram はトークンを96.6%削減しながら、その差の大部分を埋めます。比較として、最も人気のあるエージェントメモリシステムである Mem0 は、同じベンチマークで66.9%のスコアです。

---

レート制限と無料枠

Engram は Gemini の無料 API 枠で動作しますが、次の制限にご注意ください。

• 無料枠： gemini-2.5-flash は約20リクエスト／分、約1,500リクエスト／日です
• 埋め込みの呼び出しも制限に含まれます
• より余裕が必要ですか？ gemini-3.1-flash-lite などの軽量モデルは、無料枠の RPM がより高くなっています。engram init を実行する前に ENGRAM_LLM_MODEL を設定すると、MCP サーバーの設定に書き込まれます。

ENGRAM_LLM_MODEL=gemini-3.1-flash-lite engram init

Engram にはリトライ機能が組み込まれています。レート制限に達した場合、自動的に待機して最大3回まで再試行します。次のようなログメッセージが表示されます。

[engram] Gemini embedContent rate limited. Retrying in 33s (attempt 1/3)...

Engram を頻繁に使用する場合（短時間に「記憶」と「想起」を何度も行う場合）は、制限を引き上げるために有料の Gemini API キーへのアップグレードをご検討ください。

---

---

バッジ

プロジェクトで Engram を使用していますか？README にバッジを追加してください。

[![Made with Engram](https://img.shields.io/badge/memory-Engram-8B5CF6?style=flat)](https://github.com/tstockham96/engram)

---

ライセンス

MIT

---

リンク

• 📦 npm
• 💻 GitHub