Engram

🚀 Engram

AIエージェント用のイベントソーシング型メモリシステムです。書き込みパスに大規模言語モデル（LLM）は使用せず、信頼性の高いエピソードの保存と意味検索を提供します。

📖 ドキュメントを表示

🚀 クイックスタート

前提条件

• Ollama がローカル（またはリモート）で実行され、埋め込みモデルが用意されていること
• ソースからビルドする場合は、Go 1.25以上が必要

インストール

オプションA: 事前ビルド済みのバイナリをダウンロード

リリースページ から自分のプラットフォーム用のバイナリをダウンロードします。

# macOS/Linux: 実行可能にする
chmod +x engram-*
mv engram-* engram

オプションB: ソースからビルド

git clone https://github.com/OscillateLabsLLC/engram
cd engram

# justを使用する場合（推奨 — https://github.com/casey/just からインストール）
just setup    # 依存関係のインストール、埋め込みモデルの取得、ビルド

# または手動で
go build -o engram ./cmd/engram/main.go

埋め込みモデルを取得

ollama pull nomic-embed-text

実行

export DUCKDB_PATH="./engram.duckdb"
export OLLAMA_URL="http://localhost:11434"
export EMBEDDING_MODEL="nomic-embed-text"

./engram

✨ 主な機能

• 意味検索 — ベクトルの類似性を使用して関連性で結果をランク付けし、最近のものではなく検索します。
• グレースフルフォールバック — 埋め込みサービスが利用できない場合でも動作します。
• 高速クエリ — DuckDB HNSWインデックスを使用して、100ms未満でベクトル検索を行います。
• 外部API不要 — すべての埋め込みはOllamaを介してローカルで生成されます。
• シングルバイナリ — Linux、macOS、Windowsでポータブルです。
• MCPネイティブ — Claude Desktop、Claude Code、Cursorと直接統合します。

📚 ドキュメント

• MCP統合ガイド - クライアントのセットアップ、利用可能なツール、トラブルシューティング
• デプロイメントガイド - Docker Compose、Kubernetes、本番環境でのデプロイ
• アーキテクチャ - システム設計の技術的な詳細

🔧 技術詳細

アーキテクチャ

engram/
├── cmd/engram/          # エントリーポイント
├── internal/
│   ├── db/              # DuckDB操作 + VSS
│   ├── embedding/       # Ollamaクライアント
│   ├── mcp/             # MCPサーバーの実装
│   └── models/          # データモデル
├── scripts/             # ビルドとテストスクリプト
├── .github/workflows/   # CI/CD (ビルド + リリース)
└── Dockerfile           # コンテナイメージ

• 公式のMCP SDK (mark3labs/mcp-go) を使用したGoサービス
• ベクトル類似性検索（HNSWインデックス）用のVSS拡張機能付きのDuckDB
• ローカルでの埋め込み生成用のOllama（768次元、nomic-embed-text）
• MCPクライアント統合用のstdioトランスポート

アーキテクチャの詳細については、 を参照してください。

設計原則

1. 書き込みは決して失敗しない（データベースが稼働している場合）
2. 書き込みパスにLLMを使用しない — 埋め込みのみを使用し、それらは再試行可能です。
3. エピソードログが真の情報源 — 他のすべては派生したものです。
4. シンプルがベスト — ベクトル検索で80％のユースケースをカバーします。
5. ポータブル — シングルバイナリ、単一のデータベースファイル

📦 設定

環境変数を使用して設定します。

テンプレートについては、 を参照してください。

💻 使用例

MCPクライアント統合

Engramは、Model Context Protocol (MCP) を介してClaude Desktop、Claude Code、Cursorと統合します。

クイックセットアップ（ローカル）

claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "engram-memory": {
      "command": "/absolute/path/to/engram",
      "args": [],
      "env": {
        "DUCKDB_PATH": "/absolute/path/to/engram.duckdb",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

💡 使用アドバイス：絶対パスを使用してください。macOSでは、realpath engram を実行して完全なパスを取得できます。

詳細な統合手順、リモートデプロイメント、利用可能なMCPツール、およびトラブルシューティングについては、docs/mcp-integration.md を参照してください。

Dockerとデプロイメント

クイックスタート（開発用）

# macOS/Windows
just docker-up

# Linux
just docker-up-linux

Docker Compose、Kubernetes、および本番環境の構成を含む詳細なデプロイメント手順については、docs/deployment.md を参照してください。

テスト

このプロジェクトには包括的な単体テストが含まれています。

# すべてのテストを実行
just test

# カバレッジを含めて実行
just test-coverage

コントリビューション

開発環境のセットアップ、コードスタイル、およびプルリクエストの提出方法については、CONTRIBUTING.md を参照してください。

📄 ライセンス

MIT