Memory MCP Server (Go)

Memory MCP Server (Go)

ナレッジグラフ管理機能を提供する Model Context Protocol サーバーです。このサーバーを使用すると、LLM は永続的なナレッジグラフ内のエンティティや関係を作成、読み取り、更新、削除でき、AI アシスタントが会話をまたいで記憶を維持できるようになります。これは、公式の TypeScript Memory MCP Server の Go 実装です。

機能

• 高性能ストレージ：WAL モードを備えた SQLite バックエンド。並行アクセスに対応するため、読み取り用と書き込み用の接続を分離しています
• ナレッジグラフ管理：エンティティ、関係、観察結果を永続化するグラフ
• 高度な検索：BM25 ランキング、同義語の拡張、時間減衰スコアリングに対応した FTS5 全文検索
• グラフ探索：検索結果に 1 ホップ先の関連エンティティが含まれ、より豊富なコンテキストを得られます
• エンティティ管理：重複エンティティの統合、タイプの更新、観察結果の変更、競合の検出
• 観察結果のメタデータ：各観察結果のソース、信頼度、タグを追跡します
• MCP リソースとプロンプト：AI クライアントはグラフの概要を受動的に読み込み、ガイド付きの記憶ワークフローを利用できます
• 柔軟なトランスポート：stdio、SSE、Streamable HTTP に対応し、オプションで Bearer または OAuth 2.1 認証を使用できます
• シームレスな移行：介入なしで JSONL から SQLite に自動アップグレードします
• クロスプラットフォーム：Pure Go SQLite（CGO 不要）を使用し、Linux、macOS、Windows で動作します

利用可能なツール

基本的な CRUD

ツール	説明
create_entities	名前、タイプ、観察結果を指定して新しいエンティティを作成します
create_relations	エンティティ間の関係を作成します（能動態）
add_observations	既存のエンティティに観察結果を追加します
delete_entities	エンティティと関連する関係を削除します
delete_relations	指定した関係を削除します
delete_observations	エンティティから指定した観察結果を削除します

クエリ

ツール	説明
search_nodes	FTS5、同義語の拡張、グラフ探索を使用して、キーワードでエンティティを検索します。スニペットと関連エンティティを含む軽量な結果を返します
open_nodes	正確な名前を指定して、特定のエンティティの詳細を取得します
read_graph	グラフの概要（summary モード）または完全なエクスポート（full モード）を取得します

エンティティ管理

ツール	説明
merge_entities	2 つのエンティティを統合します。ソースからターゲットに観察結果と関係を移行し、ソースを削除します
update_entities	エンティティのタイプを変更します
update_observations	観察結果の内容を置き換えます
detect_conflicts	エンティティの観察結果にある重複や矛盾の可能性を検出します

MCP リソース

URI	説明
memory://graph/summary	グラフの統計情報とエンティティタイプの分布
memory://graph/recent	最近アクセスされたエンティティ
memory://graph/types	すべてのエンティティタイプと関係タイプの一覧
memory://entities/{name}	特定のエンティティの詳細

MCP プロンプト

プロンプト	説明
memory-recall	トピックに関連する記憶を呼び出します
memory-save	会話テキストを分析し、保存する内容を提案します
memory-review	エンティティの記憶を包括的にレビューします

インストール

Homebrew（macOS/Linux）

brew install okooo5km/tap/mms

クイックインストールスクリプト（macOS/Linux）

curl -fsSL https://raw.githubusercontent.com/okooo5km/memory-mcp-server-go/main/scripts/install.sh | bash

オプション：特定のバージョンを指定する場合は -v v0.2.3、カスタムディレクトリを指定する場合は -d /usr/local/bin を使用します。

ビルド済みバイナリ

GitHub Releases からダウンロードしてください。macOS（arm64/amd64）、Linux（arm64/amd64）、Windows（arm64/amd64）に対応しています。

# Example: macOS Apple Silicon
curl -L https://github.com/okooo5km/memory-mcp-server-go/releases/latest/download/mms_VERSION_darwin_arm64.tar.gz | tar xz
chmod +x mms && mv mms ~/.local/bin/

ソースからビルド

git clone https://github.com/okooo5km/memory-mcp-server-go.git
cd memory-mcp-server-go
make build        # binary in .build/

~/.local/bin（または選択したディレクトリ）が PATH に含まれていることを確認してください。

コマンドライン引数

mms [options]
  -t, --transport string   Transport type: stdio, sse, or http (default "stdio")
  -m, --memory string      Memory file path (auto-detected if not specified)
  -p, --port int           Port for SSE/HTTP transport (default 8080)
  --host string            Host/IP to bind for SSE/HTTP transports (env: MMS_HOST, default all interfaces)
  -v, --version            Show version

  Storage:
  --storage string         Force storage type: sqlite or jsonl (auto-detected)
  --auto-migrate           Auto-migrate JSONL to SQLite (default true)

  Migration:
  --migrate string         Source JSONL file for manual migration
  --migrate-to string      Destination SQLite file
  --dry-run                Dry run migration
  --force                  Overwrite destination

  Streamable HTTP:
  --http-endpoint string   HTTP endpoint path (default "/mcp")
  --http-heartbeat string  Heartbeat interval (default "30s")
  --http-stateless         Stateless HTTP mode

  Auth:
  --auth-bearer string     Require Bearer token for SSE/HTTP

  OAuth 2.1 (mutually exclusive with --auth-bearer):
  --oauth-user string      OAuth login username (env: OAUTH_USER)
  --oauth-pass string      OAuth login password (env: OAUTH_PASS)
  --oauth-issuer string    OAuth issuer URL (auto-detect if empty, env: OAUTH_ISSUER)
  --oauth-store string     SQLite path for durable OAuth clients and tokens (env: OAUTH_STORE_PATH)
  --oauth-refresh-replay-grace string
                           Duration to accept replay of a rotated refresh token (env: OAUTH_REFRESH_REPLAY_GRACE, default 75m)

  CORS:
  --cors-origin string     Allowed CORS origins: '*' for all, or comma-separated list (default "*")

例：

mms                                          # stdio, auto-detect storage
mms --memory /path/to/memory.json            # custom path, auto-migrates to SQLite
mms --transport sse --port 9000              # SSE transport
mms --transport http --auth-bearer mytoken   # Streamable HTTP with Bearer auth
mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store /var/lib/mms/oauth.db  # OAuth 2.1 auth
mms --transport http --cors-origin "https://app.example.com,https://admin.example.com"  # CORS whitelist

設定

Claude Desktop / Claude.app

"mcpServers": {
  "memory": {
    "command": "mms",
    "env": {
      "MEMORY_FILE_PATH": "/path/to/memory.json"
    }
  }
}

Claude Desktop コネクター（OAuth）

Claude Desktop のカスタムコネクターに対応した、OAuth 2.1 認証を使用するリモートデプロイの場合：

# Start server with OAuth
mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store /var/lib/mms/oauth.db --port 8080

# Or with environment variables and explicit issuer
OAUTH_USER=admin OAUTH_PASS=secret OAUTH_STORE_PATH=/var/lib/mms/oauth.db \
  OAUTH_REFRESH_REPLAY_GRACE=24h \
  mms --transport http --oauth-issuer https://mcp.example.com

その後、Claude Desktop で 設定 → コネクター → カスタムコネクターを追加 を選択し、サーバー URL（例：https://mcp.example.com/mcp）を入力します。Claude が OAuth エンドポイントを自動的に検出し、ログインを促します。

Cursor

Cursor の設定 > mcp.json に追加します：

{
  "mcpServers": {
    "memory": {
      "command": "mms",
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

システムプロンプトの例

You have access to a Knowledge Graph memory system that persists across conversations.

Saving memories:
- create_entities: Add new people, places, concepts (check search_nodes first to avoid duplicates)
- create_relations: Record how entities relate to each other
- add_observations: Add facts to existing entities

Retrieving memories:
- search_nodes: Find relevant entities by keyword (supports synonyms like JS→JavaScript)
- open_nodes: Get full details of specific entities
- read_graph: Get an overview of all stored knowledge (use "summary" mode first)

Managing memories:
- merge_entities: Combine duplicate entities
- detect_conflicts: Find contradictory observations
- update_entities / update_observations: Fix incorrect data

Always check your memory before answering questions that might require past context.

Streamable HTTP の使用方法

Streamable HTTP エンドポイントは、JSON-RPC リクエスト、通知、レスポンスを受け付けます。サーバーの ping メッセージへの返信など、クライアントからのレスポンスは MCP トランスポート仕様に従い、本文なしの 202 Accepted で応答されます。

# 1. Initialize session
curl -i -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mytoken' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

# 2. Listen for server messages
curl -N http://localhost:8080/mcp \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>'

# 3. Call a tool
curl -s http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_nodes","arguments":{"query":"idea"}}}'

# 4. Terminate session
curl -X DELETE http://localhost:8080/mcp \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>'

セキュリティとデプロイ

• TLS（Nginx/Caddy/Traefik）の背後にデプロイし、サーバーを localhost にバインドします
• 簡易認証：プログラムから利用するクライアントには --auth-bearer $(openssl rand -hex 32) を使用します
• OAuth 2.1：ブラウザーベースのログイン（Claude Desktop コネクター）には --oauth-user/--oauth-pass を使用します。本番環境では --oauth-store を設定し、登録済みクライアントとトークンが再起動後も保持されるようにしてください。また、SQLite WAL/SHM ファイルを保護するため、systemd の UMask=0077 のような制限付き umask を設定してサービスを実行してください。PKCE（S256）、動的クライアント登録、永続的なトークン保存、同時実行または複数ワーカーのクライアント向けのリプレイ猶予期間を設けたリフレッシュトークンのローテーションに対応しています。複数のプロセスで古いリフレッシュトークンを保持するクライアントには --oauth-refresh-replay-grace を使用します
• リバースプロキシからバックエンドへ Authorization ヘッダーを転送します。プロキシの背後で使用する場合は、--oauth-issuer に公開 URL を設定します
• root 以外のユーザーで実行し、必要なポートのみを開き、信頼できないクライアントに対してレート制限を有効にします

ストレージシステム

ストレージの種類

	SQLite（推奨）	JSONL（レガシー）
読み取り／検索	1.9 倍高速	基準
メモリ	1.9 倍効率的	基準
ファイルサイズ	大きい	3 倍小さい
起動	遅い	55 倍高速
機能	FTS5、ACID、WAL、並行読み取り	人間が読みやすい
最適な用途	エンティティが 100 件超	エンティティが 50 件未満

移行

# Automatic (default): just use your existing JSONL path
mms --memory /path/to/memory.json  # auto-migrates to .db

# Manual migration
mms --migrate /path/to/memory.json --migrate-to /path/to/memory.db

# Dry run
mms --migrate /path/to/memory.json --dry-run

ナレッジグラフの構造

• エンティティ：名前、種類、観察事項のリストを持つノード（各観察事項には、ソース、信頼度、タグなどのメタデータを任意で付与できます）
• リレーション：能動態のリレーション種別でエンティティ間を結ぶ有向エッジ
• 観察事項：エンティティに関連付けられた個別の事実。アクセスパターンに基づく時間減衰ランキングに対応しています

使用例

エンティティの作成

{
  "entities": [
    {
      "name": "John Smith",
      "entityType": "person",
      "observations": ["Software engineer", "Lives in San Francisco", "Enjoys hiking"]
    },
    {
      "name": "Acme Corp",
      "entityType": "company",
      "observations": ["Founded in 2010", "Tech startup"]
    }
  ]
}

リレーションの作成

{
  "relations": [
    { "from": "John Smith", "to": "Acme Corp", "relationType": "works at" }
  ]
}

グラフ走査による検索

「John」を検索すると、次の結果が返されます：

• 直接一致：観察事項の抜粋とともに、「John」に一致するエンティティ
• 関連エンティティ：リレーションを介して「John」に接続されたエンティティ（例：「works at」を介した「Acme Corp」）

重複エンティティの統合

{
  "sourceName": "React.js",
  "targetName": "React"
}

「React.js」のすべての観察事項とリレーションを「React」に統合し、その後「React.js」を削除します。

矛盾の検出

{
  "entityName": "John Smith"
}

潜在的な重複（接頭辞が 60% 超重複）と矛盾（「likes/dislikes」のような反義語のキーワードペア）を返します。

開発

make fmt          # Format code
make check        # Static analysis (gofmt + go vet)
go test ./...     # Run tests
make build        # Build binary

# Full verification
make fmt && make check && go test ./... && make build

要件

• Go 1.24+
• github.com/mark3labs/mcp-go v0.19.0+
• modernc.org/sqlite（CGO 不要の純粋な Go 製 SQLite）

バージョン管理

バージョンは VERSION ファイルで管理されます。make build VERSION=1.2.3 または go build -ldflags "-X main.version=1.2.3" で上書きできます。

ライセンス

MIT ライセンスです。詳細は LICENSE を参照してください。