Memory MCP Server

Memory MCP

永続メモリストレージ、全文検索、関係グラフのトラバーサルに対応した、SQLite ベースの MCP サーバーです。

概要

Memory MCP は、MCP 対応アシスタント向けにローカルで永続的なメモリレイヤーを提供します。SHA-256 アドレス指定のメモリアイテムを SQLite に保存し、FTS5 による全文検索、有向関係グラフ、BFS による想起トラバーサル、トークン予算を考慮したコンテキスト取得を備えています。これらすべてを外部依存関係なしで、stdio トランスポート経由で利用できます。

主な機能

• CRUD、一括操作、FTS5 検索、BFS グラフ想起、トークン予算に応じたコンテキスト取得、関係、統計情報のための 13 個の MCP ツール。
• SQLite FTS5 を使用した、重要度とタイプによるフィルターに対応したコンテンツおよびタグの 全文検索。
• BFS トラバーサル、範囲を制限したフロンティア、ホップごとの MCP 進捗通知に対応した グラフ想起。
• トークン予算に応じた取得（retrieve_context）では、呼び出し元が指定したトークン予算に収まるメモリを選択します。手動でページネーションする必要はありません。
• 型付き出力エンベロープと SHA-256 ハッシュアドレス指定に対応した 厳密な Zod 入力検証。
• internal://instructions（Markdown ガイド）と、ハッシュの自動補完に対応した URI テンプレート memory://memories/{hash} を備えた リソースサポート。
• SIGINT、SIGTERM による正常なシャットダウン処理に対応した stdio トランスポート。HTTP エンドポイントはありません。 |

要件

• Node.js >=24。
• FTS5 をサポートする SQLite（起動時に検証されます）。
• stdio コマンドサーバーに対応した任意の MCP クライアント。

クイックスタート

インストール不要で、npm パッケージを npx から直接使用できます。

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

ヒント

サーバーは stdio トランスポートのみを使用し、HTTP エンドポイントは公開しません。カスタムログ出力によって stdout を汚さないでください。

または、Docker で実行します。

docker run --rm -i ghcr.io/j0hanz/memory-mcp:latest

クライアント設定

{
  "servers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'

code-insiders --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

claude mcp add memory-mcp -- npx -y @j0hanz/memory-mcp@latest

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memory-mcp@latest"]
    }
  }
}

# Pull and run (stdio mode)
docker run --rm -i \
  -e MEMORY_DB_PATH=/data/memory.db \
  -v memory-data:/data \
  ghcr.io/j0hanz/memory-mcp:latest

{
  "mcpServers": {
    "memory-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MEMORY_DB_PATH=/data/memory.db",
        "-v",
        "memory-data:/data",
        "ghcr.io/j0hanz/memory-mcp:latest"
      ]
    }
  }
}

ドキュメントの保守

• 担当者：src/ の MCP の動作を更新するメンテナーは、同じ PR で README.md と該当する mcp/ のミラーページを更新する必要があります。
• リンク／バージョンポリシー：プロトコルの参照には固定された https://modelcontextprotocol.io/specification/2025-11-25/... リンクを使用し、latest や混在するレガシーなリンク先は避けてください。
• 差分確認チェックリスト：
  • src/server.ts の機能宣言を再確認します。
  • ツール／リソース／プロンプトのドキュメントを src/tools/index.ts、src/resources/index.ts、src/prompts/index.ts と照合します。
  • src/instructions.md の制限事項や注意点が実行時の動作と一致していることを確認します。
• 検証コマンド：npm run type-check、npm run test:fast、npm run build。

MCP のインターフェース

ツールの概要

store_memory

内容、タグ、オプションの種類／重要度を指定して、新しいメモリを保存します。冪等です。同じ内容とタグを保存すると、created: false と既存のハッシュが返されます。

戻り値：{ hash, created }

store_memories

1 回のトランザクションで複数のメモリを保存します（最大 50 件）。

戻り値：{ items, succeeded, failed }

get_memory

SHA-256 ハッシュを指定して、1 件のメモリを取得します。

戻り値：Memory、または E_NOT_FOUND の場合は { ok: false, error }。

update_memory

既存のメモリの内容を更新し、必要に応じてタグも更新します。両方のハッシュが返されます。

戻り値：{ old_hash, new_hash }

delete_memory

ハッシュを指定して、1 件のメモリを削除します。関連するリレーションシップの行も連鎖的に削除されます。

戻り値：{ hash, deleted }

delete_memories

1 回のトランザクションで、ハッシュを指定して複数のメモリを削除します。

戻り値：{ items, succeeded, failed }

search_memories

FTS5 を使用して、メモリーの内容とタグを全文検索します。重要度とタイプによるフィルターに対応し、カーソルを使ってページネーションします。

返り値：{ memories, total_returned, nextCursor? }

create_relationship

2 つのメモリー間に、有向のリレーションシップエッジを作成します。べき等です。

relation_type の値として、related_to、causes、depends_on、parent_of、child_of、supersedes、contradicts、supports、references を推奨します。

返り値：{ created }

delete_relationship

有向のリレーションシップエッジを 1 つ削除します。

返り値：E_NOT_FOUND の場合は { deleted } または { ok: false, error }。

get_relationships

メモリーのリレーションシップを取得します。方向によるフィルターを任意で指定できます。

返り値：{ relationships, count }

各リレーションシップには、from_hash、to_hash、relation_type、created_at、linked_hash、linked_content、linked_tags が含まれます。

recall

全文検索クエリでメモリを検索し、その後 BFS で最大 depth ホップまで関係グラフをたどります。各ホップで MCP の進捗通知を送信します。

戻り値：{ memories, graph, depth_reached, aborted?, nextCursor? }

graph 内の各項目は次の形式です。

{ "from_hash": "...", "to_hash": "...", "relation_type": "..." }

メモ

aborted: true は、走査が安全上の上限（RECALL_MAX_FRONTIER_SIZE、RECALL_MAX_EDGE_ROWS、または RECALL_MAX_VISITED_NODES）に達したことを示します。部分的な結果は引き続き返されます。

retrieve_context

メモリを検索し、呼び出し元が指定したトークン予算内に収まる関連度順の結果を返します。コンテキストウィンドウの管理における、手動のページネーションとトークン数のカウントが不要になります。

戻り値：{ memories, estimated_tokens, truncated }

ヒント

トークン数の推定は概算です（コンテンツの長さ ÷ 4）。truncated: true は、すべての候補を含める前に予算に達したことを示します。

memory_stats

メモリと関係の集計統計を返します。入力は不要です。

戻り値：

{
  "memories": {
    "total": 0,
    "oldest": null,
    "newest": null,
    "avg_importance": null
  },
  "relationships": { "total": 0 },
  "by_type": {}
}

リソース

プロンプト

設定

環境変数

重要

MEMORY_DB_PATH が相対パスの場合（デフォルトの memory_db/memory.db を含む）、プロセスの作業ディレクトリを基準に解決されます。

ヒント

データベースをバージョン管理の対象外にするには、.gitignore に memory_db/ を追加してください。データベースにはローカルのセッションデータが含まれるため、共有したりコミットしたりしないでください。

制限事項と制約

メモ

カーソル値は不透明な base64url エンコード済みトークンです。不透明な値として扱い、解析しないでください。

セキュリティ

• トランスポートは stdio のみ（StdioServerTransport）で、HTTP エンドポイントはありません。
• 致命的なプロセスエラーは stderr に出力されます。MCP プロトコルのため、stdout はクリーンな状態に保つ必要があります。
• データベースにアクセスする前に、すべての入力を厳格な Zod スキーマと上限付きフィールド制約で検証します。
• ハッシュは、小文字 64 文字の SHA-256 16 進数正規表現に照らして検証します。
• FTS の MATCH 実行前に検索入力を英数字の語句にトークン化します（英数字以外の文字は区切り文字として扱われ、FTS インジェクションを防ぎます）。
• SQLite の外部キーが有効になっており、メモリを削除すると関連行も連鎖削除されます。

開発

依存関係をインストールします：

npm install

主要なスクリプト：

MCP Inspector で確認します：

npx @modelcontextprotocol/inspector node dist/index.js

ビルドとリリース

GitHub Actions のリリースワークフロー（.github/workflows/release.yml）は、単一の workflow_dispatch トリガーでバージョン管理、検証、公開を処理します：

workflow_dispatch (patch / minor / major / custom)
    │
    ▼
  release — bump package.json + server.json → lint → type-check → test → build → tag → GitHub Release
    │
    ├──► publish-npm ──► publish-mcp   (npm Trusted Publishing OIDC → MCP Registry)
    │
    └──► publish-docker                (GHCR, linux/amd64 + linux/arm64)

リリースを実行します：

gh workflow run release.yml -f bump=patch

または、GitHub UI を使用します：Actions → Release → Run workflow。

メモ

npm の公開には OIDC Trusted Publishing を使用するため、NPM_TOKEN シークレットは不要です。MCP Registry では GitHub OIDC を使用します。Docker では組み込みの GITHUB_TOKEN を使用します。

トラブルシューティング

ライセンス

MIT