Smriti Mcp

Smriti MCP

EcphoryRAG 検索と Leiden クラスタリングを備えたグラフベースの AI メモリーシステム

Smriti は、LLM アプリケーションに永続的なグラフベースのメモリーを提供する Model Context Protocol（MCP）サーバーです。3 種類のデータベースバックエンド、LadybugDB（組み込み型）、Neo4j、FalkorDB に対応し、EcphoryRAG に着想を得た複数段階の検索を使用します。手がかりの抽出、グラフ探索、ベクトル類似度、マルチホップ関連付けを組み合わせ、人間のような記憶の想起を実現します。Smriti は Leiden アルゴリズムを使用してコミュニティを自動検出し、数千件を超えるメモリーにも対応できる、クラスタを考慮した検索を可能にします。

機能

• グラフベースのメモリー — エングラム（メモリー）が、プロパティグラフ内で手がかりと関連付けによってリンクされます
• EcphoryRAG 検索 — 手がかりの抽出、ベクトル類似度、複合スコアリングを用いたマルチホップの連想想起
• Leiden コミュニティ検出 — Leiden アルゴリズムとスマートキャッシュによる解像度調整を使用して、関連するメモリーを自動的にクラスタリングします。クラスタを考慮したスコアリングにより、大規模環境でも効率的な検索が可能です
• 複数バックエンドへの対応 — LadybugDB（組み込み型、設定不要）、Neo4j（エンタープライズ向けグラフ DB）、FalkorDB（Redis ベースのグラフ DB）
• マルチユーザー分離 — ファイル単位（LadybugDB）、テナント単位のプロパティまたはデータベース単位（Neo4j）、テナント単位のプロパティまたはグラフ単位（FalkorDB）
• 自動統合 — 指数減衰、弱いメモリーのプルーニング、頻繁にアクセスされるメモリーの強化、Leiden による定期的な再クラスタリング
• 柔軟なバックアップ — GitHub（システムの git）または S3（AWS SDK）との同期に対応。ローカルのみの場合は noop を使用できます
• 遅延 HNSW インデックス作成 — データセットがしきい値を超えると、ベクトルインデックスと FTS インデックスをオンデマンドで作成します
• OpenAI 互換 API — OpenAI 互換の LLM と埋め込みプロバイダーで動作します
• 3 つの MCP ツール — smriti_store、smriti_recall、smriti_manage

アーキテクチャ

graph TD
    Client["MCP Client<br/>(Cursor / Claude / Windsurf / etc.)"]
    Client -->|stdio| Server

    subgraph Server["Smriti MCP Server"]
        direction TB

        subgraph Tools["MCP Tools"]
            Store["smriti_store"]
            Recall["smriti_recall"]
            Manage["smriti_manage"]
        end

        subgraph Engine["Memory Engine"]
            Encoding["Encoding<br/>LLM + Embed + Link"]
            Retrieval["Retrieval<br/>Cue Match + Vector + Multi-hop<br/>+ Cluster-Aware Scoring"]
            Consolidation["Consolidation<br/>Decay + Prune + Leiden Clustering"]
        end

        subgraph DB["Graph Database"]
            direction LR
            Graph["(Engram)──[:EncodedBy]──▶(Cue)<br/>(Engram)──[:AssociatedWith]──▶(Engram)<br/>(Cue)──[:CoOccurs]──▶(Cue)"]
            DBType["LadybugDB | Neo4j | FalkorDB"]
        end

        subgraph Backup["Backup Provider (optional)"]
            Git["GitHub (git)"]
            S3["S3 (AWS SDK)"]
            Noop["Noop"]
        end

        Store & Recall & Manage --> Engine
        Encoding & Retrieval & Consolidation --> DB
        DB --> Backup
    end

    LLM["LLM / Embedding API<br/>(OpenAI-compatible)"]
    Engine --> LLM

想起パイプライン

デフォルトの recall モードでは、複数段階の検索を実行します。

1. 手がかりの抽出 — LLM がクエリからエンティティとキーワードを抽出します
2. 手がかりベースのグラフ探索 — EncodedBy エッジをたどり、一致する手がかりにリンクされたエングラムを見つけます
3. ベクトル類似度検索 — すべてのエングラム埋め込みとのコサイン類似度を計算します（利用可能な場合は HNSW インデックスを使用し、ない場合は総当たり検索にフォールバックします）
4. マルチホップ展開 — AssociatedWith エッジをたどり、関連するメモリーを見つけます
5. クラスタを考慮した複合スコアリング — ベクトル類似度（40%）、新しさ（20%）、重要度（20%）、減衰（20%）を組み合わせます。また、ホップ深度のペナルティと、シードクラスタ外のホップ結果に対するソフト境界付きクラスタ間ペナルティ（0.5 倍）を適用します
6. アクセスによる強化 — 想起されたエングラムのアクセス回数と減衰係数を引き上げます（強化）

Leiden クラスタリング

Smriti は Leiden アルゴリズムを使用して、関連するメモリのクラスターをグラフ内で自動検出します。これは Louvain を改良したアルゴリズムで、十分に連結されたコミュニティを保証します。

仕組み：

• 各統合サイクル中に自動で実行されます
• エングラム間の AssociatedWith エッジから、重み付き無向グラフを構築します
• 初回実行時にコミュニティプロファイリングを使用して、解像度パラメーターを自動調整します
• スマートキャッシュを使用します。調整済みの解像度は実行間で再利用され、グラフが 10% を超えて増加した場合にのみ再調整されます
• 各エングラムに cluster_id を割り当て、データベースに永続的に保存します
• 新しいエングラムは、エンコード時に最も強く結び付いた近傍の cluster_id を継承します

検索の改善方法：

• 想起パイプラインがシードクラスターを特定します（直接一致した結果の中で最も多いクラスター）
• 別のクラスターにまたがるマルチホップ結果には、スコアに 0.5 倍のペナルティが適用されます（ソフトバウンド方式のため、結果は除外されずペナルティのみが適用されます）
• これにより、関連性の高いトピッククラスター内に検索を集中させながら、トピックを越えた発見も可能にします

パフォーマンス特性：

• 小規模なグラフ（ノードが 3 個未満、またはエッジが 0 個）の場合は、安全にスキップします
• ノード 60 個のクラスタリング：約 40 ms（自動調整を伴う初回実行時）、約 14 ms（キャッシュ済み解像度の場合）
• ユーザーごと：各 Engine インスタンスは、それぞれ独立したキャッシュを保持します

統合パイプライン

統合は定期的に実行され（デフォルト：3600 秒ごと）、次の処理を行います。

1. 指数減衰 — 最後にアクセスされてからの経過時間に基づいて decay_factor を減らします
2. 弱いメモリの刈り込み — 減衰が最小しきい値を下回るエングラムを削除します
3. 頻度に基づく強化 — 頻繁にアクセスされるメモリの減衰係数を引き上げます
4. 孤立した手掛かりのクリーンアップ — どのエングラムにもリンクされていない手掛かりを削除します
5. Leiden クラスタリング — メモリグラフを再クラスタリングします（スマートキャッシュを使用し、グラフに大きな変化がなければスキップします）
6. インデックス管理 — エングラム数がしきい値（50）を超えると、HNSW ベクトルインデックスと FTS インデックスを作成します

要件

• Go 1.25 以降 — ソースからビルドする場合に必要です

• Git 2.x 以降 — GitHub バックアッププロバイダーに必要です（PATH に含まれている必要があります）

• GCC／ビルドツール — CGO（LadybugDB バックエンド）に必要です

  • macOS：xcode-select --install
  • Linux：sudo apt install build-essential
  • Windows：Docker（推奨）または MinGW を使用してください

• liblbug（LadybugDB 共有ライブラリ） — LadybugDB バックエンドの実行時依存関係です。ビルド中に go-ladybug が自動的にダウンロードします。手動でビルドする場合は、LadybugDB/ladybug から最新リリースを入手してください。

  プラットフォーム	アセット	ライブラリ
  macOS	liblbug-osx-arm64.tar.gz / liblbug-osx-x86_64.tar.gz	liblbug.dylib
  Linux	liblbug-linux-{arch}.tar.gz	liblbug.so
  Windows	liblbug-windows-x86_64.zip	liblbug.dll

  共有ライブラリは実行時にシステムのライブラリパス上にある必要があります（例：macOS では DYLD_LIBRARY_PATH、Linux では LD_LIBRARY_PATH、Windows ではバイナリと同じ場所）。Docker とリリースバイナリには、これが自動的に含まれます。

• Neo4j 5.x 以降 — DB_TYPE=neo4j を使用する場合にのみ必要です。ベクトル検索と全文検索インデックス作成には、APOC と GDS のプラグインが必要です。

• FalkorDB — DB_TYPE=falkordb を使用する場合にのみ必要です。Redis プロトコルで動作します（デフォルトポート：6379）。

クイックスタート

1. ビルド

# Build
CGO_ENABLED=1 go build -o smriti-mcp .

# Run (minimal config)
export LLM_API_KEY=your-api-key
export ACCESSING_USER=alice
./smriti-mcp

2. MCP クライアントとの統合

オプション 1：ネイティブバイナリ

Cursor（~/.cursor/mcp_settings.json）：

{
  "mcpServers": {
    "smriti": {
      "command": "/path/to/smriti-mcp",
      "env": {
        "LLM_API_KEY": "your-api-key",
        "EMBEDDING_API_KEY": "your-embedding-key"
      }
    }
  }
}

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

{
  "mcpServers": {
    "smriti": {
      "command": "/path/to/smriti-mcp",
      "args": [],
      "env": {
        "LLM_API_KEY": "your-api-key",
        "EMBEDDING_API_KEY": "your-embedding-key"
      }
    }
  }
}

Windsurf（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "smriti": {
      "command": "/path/to/smriti-mcp",
      "env": {
        "LLM_API_KEY": "your-api-key",
        "EMBEDDING_API_KEY": "your-embedding-key"
      }
    }
  }
}

オプション 2：Go Run

Node.js の npx と同様に、インストールせずに直接実行できます。

{
  "mcpServers": {
    "smriti": {
      "command": "go",
      "args": ["run", "github.com/tejzpr/smriti-mcp@latest"],
      "env": {
        "LLM_API_KEY": "your-api-key",
        "EMBEDDING_API_KEY": "your-embedding-key"
      }
    }
  }
}

オプション 3：Docker コンテナ

シンプルモード（単一ユーザー）：

{
  "mcpServers": {
    "smriti": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/.smriti:/home/smriti/.smriti",
        "-e", "LLM_API_KEY=your-api-key",
        "-e", "EMBEDDING_API_KEY=your-embedding-key",
        "tejzpr/smriti-mcp"
      ]
    }
  }
}

マルチユーザーモード：

{
  "mcpServers": {
    "smriti": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/.smriti:/home/smriti/.smriti",
        "-e", "LLM_API_KEY=your-api-key",
        "-e", "EMBEDDING_API_KEY=your-embedding-key",
        "-e", "ACCESSING_USER=yourname",
        "tejzpr/smriti-mcp"
      ]
    }
  }
}

注：

• /Users/yourname を実際のホームディレクトリのパスに置き換えてください
• MCP クライアントは JSON 設定内の $HOME や ~ を展開しません。絶対パスを使用してください
• .smriti ボリュームマウントにより、メモリデータベースが永続化されます
• コンテナは root 以外のユーザー smriti として実行されます

ローカルでビルドする（任意）：

docker build -t smriti-mcp .

設定では tejzpr/smriti-mcp の代わりに smriti-mcp を使用してください。

オプション 4：GitHub リリースバイナリ

リリースページからビルド済みバイナリをダウンロードしてください。以下のプラットフォーム向けのバイナリを利用できます。

プラットフォーム	アーキテクチャ	CGO
Linux	amd64	有効（ネイティブ）
macOS	arm64（Apple Silicon）	有効（ネイティブ）
Windows	amd64	有効（ネイティブ）

各リリースには、検証用の checksums-sha256.txt が含まれています。

環境変数

コア

変数	デフォルト	説明
ACCESSING_USER	OS ユーザー名	ユーザー識別子（DB の分離に使用）
STORAGE_LOCATION	~/.smriti	ルートストレージディレクトリ（LadybugDB のみ）
DB_TYPE	ladybug	データベースバックエンド：ladybug、neo4j、または falkordb

LLM

変数	デフォルト	説明
LLM_BASE_URL	https://api.openai.com/v1	LLM API エンドポイント（OpenAI 互換）
LLM_API_KEY	(必須)	LLM API キー
LLM_MODEL	gpt-4o-mini	LLM モデル名

埋め込み

変数	デフォルト	説明
EMBEDDING_BASE_URL	https://api.openai.com/v1	埋め込み API エンドポイント
EMBEDDING_API_KEY	(LLM_API_KEY にフォールバック)	埋め込み API キー
EMBEDDING_MODEL	text-embedding-3-small	埋め込みモデル名
EMBEDDING_DIMS	1536	埋め込みベクトルの次元数

バックアップ

変数	デフォルト	説明
BACKUP_TYPE	none	none、github、または s3
BACKUP_SYNC_INTERVAL	60	バックアップ同期の間隔（秒）（0 = 無効）
GIT_BASE_URL	(空)	Git リモートのベース URL（github の場合は必須）
S3_ENDPOINT	(空)	S3 エンドポイント（AWS 以外のプロバイダー向け）
S3_REGION	(空)	S3 リージョン（s3 の場合は必須）
S3_ACCESS_KEY	(空)	S3 アクセスキー（s3 の場合は必須）
S3_SECRET_KEY	(空)	S3 シークレットキー（s3 の場合は必須）

Neo4j（DB_TYPE=neo4j の場合）

変数	デフォルト	説明
NEO4J_URI	(必須)	Bolt URI（例：bolt://localhost:7687）
NEO4J_USERNAME	(必須)	Neo4j ユーザー名
NEO4J_PASSWORD	(必須)	Neo4j パスワード
NEO4J_DATABASE	neo4j	データベース名（database 分離モードではユーザー名で上書きされます）
NEO4J_ISOLATION	tenant	tenant（プロパティベース、Community Edition）または database（DB ごとに分離、Enterprise Edition）

FalkorDB（DB_TYPE=falkordb の場合）

変数	デフォルト	説明
FALKOR_ADDR	localhost:6379	FalkorDB Redis アドレス
FALKOR_PASSWORD	(空)	FalkorDB パスワード（認証が有効な場合）
FALKOR_GRAPH	smriti	グラフ名（graph 分離モードでは {user}_smriti で上書きされます）
FALKOR_ISOLATION	tenant	tenant（プロパティベース）または graph（グラフごとに分離）

統合

変数	デフォルト	説明
CONSOLIDATION_INTERVAL	3600	統合処理の実行間隔（秒）（0 = 無効）

MCP ツール

smriti_store

「これを記憶してください」 — 新しいメモリを保存します。内容は LLM によって自動的に分析・埋め込みされ、メモリグラフに織り込まれます。新しいエングラムは、最も類似する既存の隣接ノードの cluster_id を引き継ぎます。

{
  "content": "Kubernetes uses etcd as its backing store for all cluster data",
  "importance": 0.8,
  "tags": "kubernetes,etcd,infrastructure",
  "source": "meeting-notes"
}

パラメーター	型	必須	説明
content	string	はい	メモリの内容
importance	number	いいえ	優先度 0.0～1.0（デフォルト：0.5）
tags	string	いいえ	カンマ区切りのタグ
source	string	いいえ	ソース／出所ラベル

smriti_recall

「X について何を知っていますか？」 — クラスターを考慮したスコアリングを用いる多段階 EcphoryRAG 検索で、記憶を取得します。

{
  "query": "container orchestration tools",
  "limit": 5,
  "mode": "recall"
}

パラメーター	型	必須	説明
query	string	いいえ	自然言語のクエリ（リストモードでは省略）
limit	number	いいえ	最大結果数（デフォルト：5）
mode	string	いいえ	recall（詳細なマルチホップ）、search（高速なベクトルのみ）、または list（閲覧）
memory_type	string	いいえ	フィルター：episodic、semantic、procedural

モードの説明：

• recall（デフォルト） — 全パイプライン：手がかりの抽出 → グラフ探索 → ベクトル検索 → マルチホップ → クラスターを考慮した複合スコアリング
• search — ベクトルのみのコサイン類似度検索です。高速ですが、検索範囲は浅くなります。
• list — 検索は行いません。最終アクセス時刻順に並べた最近の記憶を返します。

smriti_manage

「これを忘れて／今すぐ同期」 — 管理操作です。

{
  "action": "forget",
  "memory_id": "abc-123-def"
}

パラメーター	型	必須	説明
action	string	はい	forget（記憶を削除）または sync（バックアップをプッシュ）
memory_id	string	forget の場合	削除する Engram ID

グラフスキーマ

Smriti は、次の構造を持つプロパティグラフに記憶を保存します。

Node Tables:
  Engram   — id, content, summary, memory_type, importance, access_count,
              created_at, last_accessed_at, decay_factor, embedding, source,
              tags, cluster_id
  Cue      — id, name, cue_type, embedding

Relationship Tables:
  EncodedBy      — (Engram) → (Cue)
  AssociatedWith — (Engram) → (Engram)  [strength, relation_type, created_at]
  CoOccurs       — (Cue) → (Cue)       [strength]

Engram ノードの cluster_id フィールドは、Leiden アルゴリズムによって管理されます。値が -1 の場合、そのエングラムはまだクラスターに割り当てられていません（例：グラフが小さすぎる、またはエングラムに関連付けがない）。

ストレージと分離

Smriti は、ストレージと分離のモデルが異なる 3 つのデータベースバックエンドをサポートしています。

LadybugDB（デフォルト）

ユーザーごとに独立した組み込みデータベースファイルが用意されます。

~/.smriti/
└── {username}/
    └── memory.lbug     # LadybugDB property graph database

STORAGE_LOCATION 環境変数でルートを指定します。ACCESSING_USER 環境変数で、開くユーザーの DB を選択します。バックアッププロバイダーは、ユーザーディレクトリをリモートストレージに同期します。

Neo4j

NEO4J_ISOLATION で制御する、次の 2 つの分離モードがあります。

• tenant（デフォルト） — すべてのユーザーで 1 つのデータベースを共有します。各ノードに user プロパティが設定され、すべてのクエリでこのプロパティに基づくフィルタリングが行われます。Neo4j Community Edition で動作します。
• database — ユーザーごとに個別の Neo4j データベースが用意されます。Neo4j Enterprise Edition が必要です。

FalkorDB

FALKOR_ISOLATION で制御する、次の 2 つの分離モードがあります。

• tenant（デフォルト） — すべてのユーザーで 1 つのグラフを共有します。各ノードに user プロパティが設定され、すべてのクエリでこのプロパティに基づくフィルタリングが行われます。
• graph — ユーザーごとに個別のグラフが用意されます（名前は {user}_smriti）。

スキーマのマイグレーション（既存のデータベースへの cluster_id の追加など）は、起動時に自動で実行されます。

プロジェクト構成

smriti-mcp/
├── main.go              # Entry point, server setup, signal handling
├── config/              # Environment variable parsing
├── llm/                 # OpenAI-compatible HTTP client (LLM + embeddings)
├── db/                  # Database backends (LadybugDB, Neo4j, FalkorDB), schema, indexes, migrations
├── memory/
│   ├── engine.go        # Engine struct, consolidation loop
│   ├── types.go         # Engram, Cue, Association, SearchResult structs
│   ├── encoding.go      # Store pipeline: LLM extraction → embed → link → cluster inherit
│   ├── retrieval.go     # Recall pipeline: cue search → vector → multi-hop → cluster scoring
│   ├── search.go        # Search modes: list, vector-only, FTS, hybrid
│   ├── consolidation.go # Decay, prune, strengthen, orphan cleanup
│   └── leiden.go        # Leiden clustering: graph build, auto-tune, smart cache, batch write
├── backup/              # Backup providers: noop, github (git), s3 (AWS SDK)
├── tools/               # MCP tool definitions: store, recall, manage
└── testutil/            # Shared test helpers

テスト

# Run unit tests
CGO_ENABLED=1 go test ./...

# Verbose with all output
CGO_ENABLED=1 go test -v ./...

# Specific package
CGO_ENABLED=1 go test -v ./memory/...
CGO_ENABLED=1 go test -v ./tools/...

# Leiden clustering tests only
CGO_ENABLED=1 go test -v -run "TestRunLeiden|TestNeedsRetune|TestDetermineSeedCluster" ./memory/

E2E／統合テスト

E2E テストでは実際の LLM／埋め込みサービスが必要です。テストは integration ビルドタグによって制御されます。

# LadybugDB E2E (no external DB required)
CGO_ENABLED=1 go test -tags integration -v -run "TestE2E_LadybugDB" ./memory/

# Neo4j E2E (requires running Neo4j instance)
NEO4J_URI="bolt://localhost:7687" NEO4J_USERNAME="neo4j" NEO4J_PASSWORD="yourpass" \
  CGO_ENABLED=1 go test -tags integration -v -run "TestE2E_Neo4j" ./memory/

# FalkorDB E2E (requires running FalkorDB instance)
FALKOR_ADDR="localhost:6379" \
  CGO_ENABLED=1 go test -tags integration -v -run "TestE2E_FalkorDB" ./memory/

# All E2E tests
CGO_ENABLED=1 go test -tags integration -v -run "TestE2E_" ./memory/

すべての E2E テストで、LLM_BASE_URL、LLM_API_KEY、LLM_MODEL、EMBEDDING_BASE_URL、EMBEDDING_MODEL、EMBEDDING_API_KEY の環境変数が必要です。

貢献

貢献を歓迎します。次の点をご確認ください。

• すべてのテストが成功すること（CGO_ENABLED=1 go test ./...）
• コードが適切にフォーマットされていること（go fmt ./...）
• 新しいコードに SPDX ライセンスヘッダーが含まれていること

貢献者の一覧については、CONTRIBUTORS.md をご覧ください。

ライセンス

このプロジェクトは、v1.0.7 以降、GNU Affero General Public License v3.0（AGPL-3.0）の下でライセンスされています。

v1.0.7 より前のバージョンは、Mozilla Public License 2.0 の下でライセンスされています。