engram-server

---

Engram は、AI エージェントのための永続メモリレイヤーです。会話から事実を抽出し、時系列ナレッジグラフに保存して、セマンティック検索とキーワード検索を組み合わせたハイブリッド検索で取得します。単一の SQLite ファイルまたは PostgreSQL データベースを基盤とします。

次の 2 つの形態で提供されます。

• jamjet-engram — 独自のアプリケーションに組み込める Rust ライブラリです。
• jamjet-engram-server（このクレート）— stdio 経由の MCP と HTTP 経由の REST に対応するスタンドアロンバイナリです。コードを書かずに Claude Desktop、Cursor、あらゆる HTTP クライアントから利用できます。

Engram はプロバイダーに依存しません。5 種類の LLM バックエンドがすぐに使える状態で組み込まれており、さらに 6 つ目の command を使えば、任意の外部スクリプトをシェルから実行できます。Rust コードに手を加えずに、Engram が標準で対応していないプロバイダーを接続できます。

ENGRAM_LLM_PROVIDER=	機能
ollama（デフォルト）	/api/chat 経由でローカルの Ollama を利用します。無料で、API キーは不要です。ノート PC で実行できます。
openai-compatible	OpenAI のチャット補完プロトコルに対応するあらゆるエンドポイント — 詳細は以下の一覧をご覧ください。
anthropic	Messages API 経由で Anthropic Claude を利用します。
google	ネイティブ JSON モードを備えた generateContent 経由で Google Gemini を利用します。
command	ユーザー指定のスクリプトをシェルから実行します。再コンパイル不要で、拡張性は無限です。
mock	テスト専用の決定的なバックエンドです — 空の事実を返します。

ENGRAM_LLM_PROVIDER=… で 1 つ選択します。同じバイナリですべてのプロバイダーを利用できます。

プロジェクトの状況、2026 年 4 月時点。 Engram は新しいプロジェクトです — v0.3.2 で、コミュニティは小規模であり、LongMemEval / DMR の公開数値はまだありません。以下のアーキテクチャは動作し、テストは合格し、Docker イメージも実行できます。今すぐ本番規模のメモリが必要な場合は、Mem0 Cloud や Zep Cloud のほうが成熟しています。Python、Postgres、Qdrant、Neo4j を必要とせず、試用できてセルフホスト可能な単一バイナリのメモリレイヤーをお探しなら、Engram はそのために作られています。

なぜEngramなのか？

課題	Engramの回答
どのエージェントメモリライブラリもPythonが中心です	RustコアにネイティブのPython、Java、MCPクライアントを搭載 — サイドカーは不要です
試すだけなのにPostgres + Qdrant + Neo4jが必要です	単一のSQLiteファイル（インフラ不要）、または必要に応じてPostgresを利用できます
会話履歴はナレッジメモリではありません	事実抽出パイプライン — メッセージから構造化された事実を取り出します
古い事実はずれたり、互いに矛盾したりします	矛盾検出 + 統合 — 減衰、昇格、重複排除、要約、振り返りを行います
メモリの想起はセマンティック検索かキーワード検索のどちらかです	ハイブリッド検索 — ベクトル検索 + SQLite FTS5を1つのクエリで実行します
エージェントはプロセス間でメモリを失います	デフォルトで永続化 — SQLiteまたはPostgresを使用し、クラッシュに強く、持ち運び可能です
MCPへの対応は後回しにされています	MCPネイティブ — 単一のバイナリで7つのツールを公開します
エージェントが何を知っていたかを遡れません	時間的ナレッジグラフ — すべての事実にスコープとタイムスタンプが設定されます
ユーザーやテナントごとにメモリを分離できません	第一級のスコープ — org / user / sessionがすべてのクエリに組み込まれています

---

クイックスタート — 30秒

Engramは、Ollama（デフォルト — 無料、ローカル）、OpenAI、Anthropic Claude、Google Geminiの4つのLLMプロバイダーに標準で対応しています。いずれかを選択してください。

オプションA — Ollama（無料、ローカル、APIキー不要）

要件： llama3.2とnomic-embed-textを取得済みのOllama：

ollama pull llama3.2
ollama pull nomic-embed-text

Docker（最も簡単）：

docker run --rm -i \
  -v engram-data:/data \
  ghcr.io/jamjet-labs/engram-server:0.3.2

コンテナはデフォルトでhost.docker.internal:11434のOllamaに接続します — MacとWindowsのDocker Desktopではそのまま動作します。Linuxユーザーは--add-host=host.docker.internal:host-gatewayが必要です。

オプションB — Anthropic Claude（ホステッド、最高品質）

docker run --rm -i \
  -e ENGRAM_LLM_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v engram-data:/data \
  ghcr.io/jamjet-labs/engram-server:0.3.2

デフォルトはclaude-haiku-4-5-20251001です。-e ENGRAM_ANTHROPIC_MODEL=claude-sonnet-4-6で変更できます。

注：AnthropicにはネイティブのJSONモードがないため、Engramはテキスト応答からJSONを解析します。llm_util::extract_json_payloadヘルパーは、Claudeがときどき出力するMarkdownのフェンスを取り除きます。

オプションC — Google Gemini

docker run --rm -i \
  -e ENGRAM_LLM_PROVIDER=google \
  -e GOOGLE_API_KEY=AIza... \
  -v engram-data:/data \
  ghcr.io/jamjet-labs/engram-server:0.3.2

デフォルトはgemini-flash-latestです。-e ENGRAM_GOOGLE_MODEL=gemini-2.5-flashで変更できます。

オプションD — 任意のOpenAI互換エンドポイント

docker run --rm -i \
  -e ENGRAM_LLM_PROVIDER=openai-compatible \
  -e OPENAI_API_KEY=sk-... \
  -v engram-data:/data \
  ghcr.io/jamjet-labs/engram-server:0.3.2

デフォルトではOpenAI自体（https://api.openai.com/v1、gpt-4o-mini）を使用します。再コンパイルせずに、環境変数を1つ変更するだけで以下のプロバイダーを指定できます：

プロバイダー	ENGRAM_OPENAI_BASE_URL=	注記
OpenAI	https://api.openai.com/v1	デフォルト
Azure OpenAI	https://<resource>.openai.azure.com/openai/deployments/<deployment>
Groq	https://api.groq.com/openai/v1	推論が非常に高速
Together.ai	https://api.together.xyz/v1
Mistral	https://api.mistral.ai/v1
DeepSeek	https://api.deepseek.com/v1
Perplexity	https://api.perplexity.ai
OpenRouter	https://openrouter.ai/api/v1	1つのキーで多数のモデルを利用
Fireworks	https://api.fireworks.ai/inference/v1
vLLM（セルフホスト）	http://your-host:8000/v1
LM Studio	http://localhost:1234/v1	ローカルのデスクトップアプリ
LocalAI	http://localhost:8080/v1	セルフホスト
Ollama /v1互換レイヤー	http://localhost:11434/v1	Ollamaの代替パス
社内のLLMゲートウェイ	インフラチームが公開する任意のURL

openaiは後方互換性のためのopenai-compatibleのエイリアスとして使用できます。

オプション E — command（シェルから任意のコマンドを実行）

Engram に標準で組み込まれていないプロバイダー（カスタム RPC の背後にある社内モデル、生の SOAP エンドポイント、ローカルの推論バイナリ、Python SDK の簡易ラッパー、あるいは今後登場する新しいプロバイダー）には、command バックエンドを使用します。Engram は抽出呼び出しごとにスクリプトを起動し、JSON リクエストを標準入力に渡して、標準出力から JSON レスポンスを読み取ります。

仕様。 スクリプトは標準入力から 1 つの JSON オブジェクトを読み取ります。

{"system": "<extraction prompt>", "user": "<conversation text>", "structured": true}

次に、標準出力へ 1 つの JSON 値を書き込みます。単独の値を返す方法：

{"facts": [{"text": "...", "entities": [...], "confidence": 0.95, "category": "..."}]}

または、エラーを表面化するのに便利なエンベロープを返す方法：

{"content": {"facts": [...]}}
{"error": "rate limited, try again"}

成功時は終了コード 0、失敗時はゼロ以外の終了コード（標準エラー出力を伴います）を返します。

Python ラッパーの例（約 15 行）：

#!/usr/bin/env python3
# my-llm.py — wraps any Python SDK for Engram.
import json, sys
from my_llm_sdk import chat  # your SDK

req = json.loads(sys.stdin.read())
resp = chat(
    system=req["system"],
    user=req["user"],
    json_mode=req.get("structured", False),
)
sys.stdout.write(json.dumps(resp))

Engram から指定します：

docker run --rm -i \
  -e ENGRAM_LLM_PROVIDER=command \
  -e ENGRAM_LLM_COMMAND="python /scripts/my-llm.py" \
  -v $(pwd)/scripts:/scripts \
  -v engram-data:/data \
  ghcr.io/jamjet-labs/engram-server:0.3.2

タイムアウトのデフォルトは 120 秒です。ENGRAM_LLM_COMMAND_TIMEOUT=30 で変更できます。

セキュリティ： command プロバイダーは、Engram プロセスのユーザーとして任意のコマンドを実行します。信頼できないユーザーが ENGRAM_LLM_COMMAND を設定できるマルチテナント環境では、絶対に使用しないでください。これはローカルかつシングルテナント向けの機能です。

オプション F — cargo install（すべてのプロバイダーで同じバイナリ）

cargo install jamjet-engram-server
engram serve                                            # ollama (default)
ENGRAM_LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=... engram serve
ENGRAM_LLM_PROVIDER=command ENGRAM_LLM_COMMAND="python /path/to/wrapper.py" engram serve

オプション G — テスト用の REST モード

engram serve --mode rest --port 9090

curl -X POST http://localhost:9090/v1/memory \
  -H 'content-type: application/json' \
  -d '{
    "user_id": "alice",
    "messages": [
      {"role": "user", "content": "I am allergic to peanuts and I love sourdough."}
    ]
  }'

curl 'http://localhost:9090/v1/memory/recall?q=food%20allergies&user_id=alice'

サーバーも設定も Python サイドカーも不要です。バイナリ 1 つで動作します。

---

MCP クライアントの設定

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）

{
  "mcpServers": {
    "engram": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "engram-data:/data",
        "ghcr.io/jamjet-labs/engram-server:0.3.2"
      ]
    }
  }
}

Cursor／MCP 対応 IDE

同じ docker run コマンド、またはローカルにインストールした engram serve バイナリを指定します。再起動すると、モデルで 11 個のツール（memory_* が 7 個、messages_* が 4 個）を利用できるようになります。

---

MCP ツール

メモリツール（7 個）

ツール	機能
memory_add	会話メッセージから事実を抽出して保存します（抽出には LLM を呼び出します）
memory_recall	保存された事実を意味検索します。user_id／org_id でスコープを指定できます
memory_context	ティアを考慮して選択し、トークン予算に合わせたコンテキストブロックを LLM プロンプト用に組み立てます
memory_search	事実をキーワード検索します（SQLite FTS5／Postgres 全文検索）
memory_forget	ID を指定して事実を論理削除します。理由は任意です
memory_stats	事実の総数、有効な事実、エンティティ、関係の集計数を表示します
memory_consolidate	統合サイクルを実行します。古くなった事実を減衰させ、価値の高い事実を昇格させ、重複に近い事実を重複排除します

すべて (org_id, user_id, session_id) でスコープ指定されます。org が最も広く、session が最も限定的です。

メッセージストアツール（4 個）

ツール	機能
messages_save	会話のチャットメッセージを保存します（任意で事実抽出を実行します）
messages_get	ID で指定した会話のすべてのメッセージを取得します
messages_list	すべての会話 ID を一覧表示します
messages_delete	会話のすべてのメッセージを削除します

---

REST API

13 個のエンドポイントが /v1/memory をルートとして提供されます。OpenAPI 形式の全エンドポイント：

メソッド	パス	ハンドラー
GET	/health	稼働状態の確認
POST	/v1/memory	メッセージを追加します（事実抽出）
GET	/v1/memory/recall?q=…&user_id=…	意味検索
POST	/v1/memory/context	トークン予算に合わせたコンテキストの組み立て
GET	/v1/memory/search?q=…&user_id=…	キーワード検索
GET	/v1/memory/stats	統計情報の集計
POST	/v1/memory/consolidate	統合を実行
DELETE	/v1/memory/facts/:id	事実を忘却
DELETE	/v1/memory/users/:id	GDPR に基づくユーザーデータの削除
POST	/v1/memory/messages	会話のメッセージを保存
GET	/v1/memory/messages	会話 ID を一覧表示
GET	/v1/memory/messages/:id	会話のメッセージを取得
DELETE	/v1/memory/messages/:id	会話を削除

---

設定

すべての設定は CLI フラグまたは環境変数で指定します。Docker イメージの設定には、環境変数を使用することを推奨します。

コア

CLI フラグ	環境変数	デフォルト	備考
--db	ENGRAM_DB_PATH	engram.db	SQLite ファイルのパス、または postgres://… 接続 URL
--extract-on-save	ENGRAM_EXTRACT_ON_SAVE	true	チャットメッセージの保存時に事実の抽出を有効にします
--mode	ENGRAM_MODE	mcp	mcp（stdio）または rest（HTTP）
--port	ENGRAM_PORT	9090	REST モードでの HTTP ポート
--llm-provider	ENGRAM_LLM_PROVIDER	ollama	ollama、openai-compatible（別名 openai）、anthropic、google、command、mock
--embedding-provider	ENGRAM_EMBEDDING_PROVIDER	ollama	ollama または mock（クラウド埋め込みプロバイダーは今後対応予定です）
--embedding-model	ENGRAM_EMBEDDING_MODEL	nomic-embed-text	Ollama の埋め込みモデル
--embedding-dims	ENGRAM_EMBEDDING_DIMS	768	埋め込みモデルの出力と一致している必要があります

Ollama

CLI フラグ	環境変数	デフォルト
--ollama-url	ENGRAM_OLLAMA_URL	http://localhost:11434（Docker イメージの場合：http://host.docker.internal:11434）
--ollama-llm-model	ENGRAM_OLLAMA_LLM_MODEL	llama3.2

OpenAI 互換（OpenAI、Groq、Together、Mistral、DeepSeek、Azure、vLLM、…）

CLI フラグ	環境変数	デフォルト
--openai-api-key	OPENAI_API_KEY	(プロバイダーが openai-compatible の場合は必須)
--openai-base-url	ENGRAM_OPENAI_BASE_URL	https://api.openai.com/v1 — プロバイダーを切り替えるには、ここを変更してください。上の大きな表を参照してください
--openai-model	ENGRAM_OPENAI_MODEL	gpt-4o-mini

Anthropic

CLI フラグ	環境変数	デフォルト
--anthropic-api-key	ANTHROPIC_API_KEY	(プロバイダーが anthropic の場合は必須)
--anthropic-base-url	ENGRAM_ANTHROPIC_BASE_URL	https://api.anthropic.com
--anthropic-model	ENGRAM_ANTHROPIC_MODEL	claude-haiku-4-5-20251001

Google Gemini

CLI フラグ	環境変数	デフォルト
--google-api-key	GOOGLE_API_KEY	(プロバイダーが google の場合は必須)
--google-base-url	ENGRAM_GOOGLE_BASE_URL	https://generativelanguage.googleapis.com/v1beta
--google-model	ENGRAM_GOOGLE_MODEL	gemini-flash-latest

Command（シェル経由で実行）

CLI フラグ	環境変数	デフォルト
--llm-command	ENGRAM_LLM_COMMAND	(プロバイダーが command の場合は必須) — sh -c 経由で実行
--llm-command-timeout	ENGRAM_LLM_COMMAND_TIMEOUT	120 — 子プロセスを終了するまでの秒数

mock バックエンドは、空の事実と決定論的なバイト循環ベクトルを返します。これはテストと CI 用です。サーバーは起動時に、モックモードが使用されていることを検出すると、明確な警告を表示します。API キーとコマンドの内容が標準出力やログに出力されることはありません。サーバーが表示するのは provider model at base_url または command \<first 60 chars>`` のみです。

---

データベースバックエンド

Engram は SQLite（デフォルト）と PostgreSQL のバックエンドに対応しています。バックエンドは --db URL で選択します。

# SQLite (default)
engram serve --mode rest --db engram.db

# PostgreSQL
engram serve --mode rest --db postgres://user:pass@localhost:5432/engram

PostgreSQL を使用する場合、テーブルは初回起動時に自動作成されます。

---

チャットメッセージストア

Engram は、抽出した事実とともに未加工のチャットメッセージを保存できます。これにより、Spring AI の ChatMemoryRepository との統合が可能になります。

REST エンドポイント：

メソッド	エンドポイント	説明
POST	/v1/memory/messages	会話のメッセージを保存します
GET	/v1/memory/messages	会話 ID の一覧を取得します
GET	/v1/memory/messages/{id}	会話のメッセージを取得します
DELETE	/v1/memory/messages/{id}	会話を削除します

MCP ツール： messages_save、messages_get、messages_list、messages_delete

メッセージ保存時の事実抽出は、--extract-on-save で制御します（デフォルト：true）。

---

ライブラリの組み込み

別プロセスを実行したくない場合は、jamjet-engram に直接依存関係を追加します。

[dependencies]
jamjet-engram = "0.3.2"

use engram::{Memory, OllamaEmbeddingProvider, OllamaLlmClient, Scope, ExtractionConfig, Message};

let embedding = Box::new(OllamaEmbeddingProvider::new());
let memory = Memory::open("sqlite:engram.db?mode=rwc", embedding).await?;

let scope = Scope::user("default", "alice");
let messages = vec![Message {
    role: "user".into(),
    content: "I am allergic to peanuts.".into(),
}];

let llm = Box::new(OllamaLlmClient::new());
let fact_ids = memory
    .add_messages(&messages, scope.clone(), llm, ExtractionConfig::default())
    .await?;

// Later, recall
let facts = memory.recall(&engram::memory::RecallQuery {
    query: "food allergies".into(),
    scope: Some(scope),
    max_results: 5,
    as_of: None,
    min_score: None,
}).await?;

---

その他の言語

Engram は JamJet エコシステムの一部です。これらのクライアントは REST 経由で engram-server と通信します。

言語	パッケージ	インストール
Python	jamjet（EngramClient を含む）	pip install jamjet
Java	dev.jamjet:jamjet-sdk（EngramClient を含む）	Maven Central
Spring Boot	dev.jamjet:engram-spring-boot-starter	Maven Central — 設定不要の @Bean EngramMemory
Rust	jamjet-engram（直接組み込み）	cargo add jamjet-engram

Engram と LangChain4j ChatMemory、Spring AI ChatMemory、Koog、Embabel、Google ADK Memory Bank、Mem0 のコミュニティラッパー、Zep との比較については、java-ai-memory.dev をご覧ください。Engram が適している用途と、代替製品のほうが成熟している領域についても、率直に説明しています。

---

アーキテクチャ

┌──────────────────────────────────────────────────────────┐
│           Clients: Claude Desktop, Cursor, JamJet,        │
│           Python SDK, Java SDK, Spring Boot, cURL         │
├─────────────────┬────────────────────────────────────────┤
│   MCP (stdio)   │           REST (HTTP + JSON)            │
├─────────────────┴────────────────────────────────────────┤
│                     engram-server                         │
│                 (jamjet-engram-server)                    │
├──────────────────────────────────────────────────────────┤
│                       engram (lib)                        │
│   Extraction pipeline  │  Hybrid retrieval  │  Scopes     │
│   Conflict detection   │  Consolidation     │  Context    │
├──────────────────────────────────────────────────────────┤
│    LlmClient trait        │    EmbeddingProvider trait    │
│    Ollama · Mock          │    Ollama · Mock              │
├──────────────────────────────────────────────────────────┤
│                       Storage                             │
│   SQLite or PostgreSQL (facts, entities, FTS, vectors)   │
└──────────────────────────────────────────────────────────┘

---

Engram が該当しないもの

• 単なるチャット履歴ストアではありません。 Engram にはメッセージストアが含まれるようになりました（チャットメッセージストアを参照）が、主な価値は、その上に構築される事実抽出とナレッジグラフのレイヤーにあります。会話の直近 N 件のメッセージだけが必要な場合は、フレームワークに組み込まれたウィンドウ機能のほうがシンプルかもしれません。
• 状態チェックポインターではありません。 エージェントの実行状態をスナップショット化して再開やリプレイを行う必要がある場合は、LangGraph、Koog の永続化機能、または JamJet 独自の永続ランタイムを使います。Engram と組み合わせてください。これらはそれぞれ異なる問題を解決します。
• マネージドサービスではありません。 ホストされたコントロールプレーンはなく、スコープ以外の認証レイヤーもなく、SLA もありません。プロセスマネージャーはご自身で用意してください。
• ベンチマークはまだ実施していません。 LongMemEval と DMR の数値はロードマップに含まれています。公開されるまでは、比較に関する主張を適切な懐疑心を持って受け止めてください。

---

ロードマップ

ステータス	項目
✅	事実抽出パイプライン + SQLite ストレージ
✅	ハイブリッド検索（ベクトル + プレフィックスマッチングを備えた FTS5）
✅	統合エンジン（減衰、昇格、重複排除、要約、内省）
✅	MCP stdio サーバー（7 個のツール）
✅	REST API（9 個のエンドポイント）
✅	複数プロバイダーに対応する LLM バックエンド：Ollama、OpenAI 互換（OpenAI/Azure/Groq/Together/Mistral/vLLM/LM Studio/…）、Anthropic、Google、command によるシェル呼び出し
✅	Python、Java、Spring Boot クライアント
✅	Docker イメージ、MCP Registry への公開
✅	Postgres バックエンド（SQLite と並行して利用可能）
✅	チャットメッセージストア + Spring AI ChatMemoryRepository 統合
📋	LongMemEval + DMR ベンチマークスコア
📋	Quarkus 拡張機能
📋	クラウド埋め込みプロバイダー（OpenAI text-embedding-3、Google text-embedding-004）

---

ライセンス

Apache 2.0 — LICENSE をご覧ください。

---