MCP-Memory: OKFとSQLite FTS5による高速なエージェントメモリ

クイック・テイク

MCP-Memoryは、AIエージェントに永続的でOKF-v0.2準拠のメモリを提供します。このメモリはローカルのSQLite FTS5データベースにインデックス化されており、20ms未満のキー検索と即時の全文検索を実現しつつ、人間が閲覧可能なMarkdownディレクトリも保持します。

MCP-Memoryとは

MCP-Memoryは、Claude Desktop、Cursor、Antigravity、Windsurf、Codexなどのエージェントに、長期的で検索可能なメモリを装備させるModel Context Protocol (MCP) サーバーです。各メモリレコードは、豊富なYAMLフロントマターを持つOKF v0.2 Markdownドキュメントとして保存され、同じデータが高速な検索のためにSQLite FTS5にインデックス化されます。

コア・デザイン・チョイス

二層アーキテクチャ

  • 人間が閲覧可能なOKFディレクトリ – すべてのメモリは、階層的な index.md ファイルを持つ .md ファイルとして memory/ に書き出され、バージョン管理可能な読みやすいナレッジベースを提供します。
  • 高性能SQLiteインデックス – FTS5トリガーを備えたSQLiteデータベースにより、20ms未満でのキー・バリュー検索と、キー、フロントマター、コンテンツを横断するキーワード検索を可能にします。

ネームスペースの分離

メモリはネームスペース（例：user/preferences、project/architecture、default）によってパーティション化でき、プロジェクト間での混同を防ぎます。

ボイラープレートなしのセットアップ

python3 setup.py を実行すると、サポートされているエージェントを自動検出し、memory MCPサーバーを登録します。これにより、エージェントは永続的なターミナルプロセスなしで、必要に応じてサーバーを自動的に起動します。

エージェントに公開されるMCPツール

ツール 目的 主要なパラメータ
memory_store メモリレコードの作成または更新 key, content, project_root, オプションの tags, namespace, concept_type, title, description, resource, status, stale_after, sources, verified, generated_by
memory_retrieve キーによる単一レコードの取得 key, project_root, オプションの namespace
memory_search 全文検索またはタグベースの検索 project_root, オプションの query, tags, namespace, limit
memory_get_last 起動時にセッションのチェックポイント (system/last_memory) を取得 project_root, オプションの namespace
memory_update_last マイルストーン後のチェックポイントの更新 content, project_root, オプションの namespace, summary

実践におけるOKF v0.2 仕様

各メモリは、以下のようなOKFフロントマター・スキーマに従います：

---
type: Agent Memory
title: Coding Style
key: user/preferences/coding_style
namespace: default
tags:
  - preferences
  - style
status: stable
generated:
  by: mcp-memory/0.2.0
  at: '2026-08-12T19:23:35Z'
created_at: '2026-08-12T19:23:35Z'
updated_at: '2026-08-12T19:23:35Z'
---
User prefers functional programming style with explicit type annotations.

同じファイルが memory/ に存在する一方で、検索可能な表現は .mcp_memory/memories.db に保存されます。

インストール & クイックスタート

  1. リポジトリを Clone する:
    git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory
  2. セットアップウィザードを実行して、サポートされているエージェントにサーバーを自動登録する:
    python3 setup.py
    完了後、エージェントが必要に応じて mcp-memory を起動します。
  3. デバッグ用の オプションの手動起動:
    /run.sh

手動クライアント設定

明示的な設定を好む場合は、run.sh を指す memory エントリを追加してください：

JSON (Antigravity, Claude Desktop, Cursor, Windsurf)

{
  "mcpServers": {
    "memory": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

TOML (Codex Desktop)

[mcp_servers.memory]
command = "/ABSOLUTE/PATH/TO/run.sh"

CLI 例

claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh

ストレージレイアウト & 環境変数

  • OKF markdown – プロジェクトルート内の memory/ ディレクトリ。
  • SQLite index – .mcp_memory/memories.db (隠しファイル)。
  • 環境変数によりカスタムの場所を指定可能です：
    • MCP_MEMORY_PROJECT_ROOT – デフォルトは現在の作業ディレクトリ。
    • MCP_MEMORY_DB_PATH – デフォルトは .mcp_memory/memories.db。
    • MCP_MEMORY_DIR – デフォルトは memory。
  • プロジェクト間で単一のストアを共有するには、MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db および MCP_MEMORY_DIR=~/.mcp_memory/memory を設定してください。

コミュニティ・フィードバックのハイライト

@myshapeprotocol – “高速なエージェントメモリにSQLite FTS5を使用するのは、非常に実用的なアーキテクチャの選択です。素晴らしいShow HNプロジェクトです。”

@bearjaws – “また新しいエージェントメモリシステムが登場した。memory/ ディレクトリに対して grep を実行するのと大差ない。”

@healthycoder – “他のMemory系ツール（mem0など）と何が違うのですか？”

@jrflo – “単にMarkdownファイルを使ってエージェントに grep させるのと比べて、なぜこれが有益なのですか？MCPツールはエージェントの動作を遅らせ、トークンを浪費すると感じています。”

@FitchApps – “なぜプレーンなMDファイルではなく、GoogleのOKF形式を使うのか、初心者向けに説明してくれますか？”

@rcarmo – “OKFベースのアプローチが増えて嬉しいです。私のプロジェクトはこちらです: https://rcarmo.github.io/projects/memento/。”

これらのコメントは、2つの繰り返されるテーマを浮き彫りにしています。それは、プレーンなMarkdownに対する構造化されたOKFメタデータの価値と、単純なgrepと比較した際のSQLiteインデックスのパフォーマンス・トレードオフです。

MCP-Memory が既存のソリューションと異なる点

  • 標準化されたメタデータ – OKF v0.2は、プレーンなMarkdownにはない一貫したスキーマ（type, tags, status, provenance）を強制し、より豊かなフィルタリングと自動化されたライフサイクル管理を可能にします。
  • 20ms未満のインデックス検索 – SQLite FTS5は決定論的なレイテンシを提供しますが、grepはファイルサイズに応じて線形にスケールし、大規模プロジェクトではボトルネックになる可能性があります。
  • 二重の永続性 – エージェントはデータベースを介して即座にマシン読み取り可能なアクセスが可能になり、開発者はレビューやバージョン管理のために人間が読みやすいMarkdownアーカイブを保持できます。
  • ネームスペースの分離 – 異なる知識ドメインを分離するための組み込みサポートにより、無関係なプロジェクト間での偶発的な混同を防ぎます。

MCP-Memory を使用すべき場面

  • 数十から数千の知識スニペットの高速で決定論的な取得が必要なプロジェクト。
  • 監査可能性を求めるチーム：Markdownディレクトリはバージョン管理が可能であり、データベースはエージェントの動作を支えます。
  • コンプライアンスやドキュメンテーションのために、構造化された出所情報（ソース、検証、ステータス）の恩恵を受けるワークフロー。

制限事項 & 未解決の課題

  • ベクトル検索機能は内蔵されていません。メモリは、正確なキー、タグ、または全文一致によってのみ取得されます。
  • パフォーマンスの向上はSQLiteのFTS5設定に依存します。極めて大規模なコーパスでは、依然としてシャーディングが必要になる場合があります。
  • エージェントが繰り返しサーバーにクエリを投げると、MCPツールによってトークン使用量が増加する場合があるとの報告があります。慎重なプロンプト設計が必要です。

結論

MCP-Memoryは、GoogleのOpen Knowledge FormatとSQLite FTS5を組み合わせることで、人間が読みやすいナレッジベースと高性能なエージェントメモリの間の溝を埋めます。その二層設計、ネームスペースの分離、およびボイラープレートなしのセットアップは、AIエージェントのための構造化された、高速で永続的なコンテキストを求める開発者にとって魅力的な選択肢となります。

Sources

関連

  • プロジェクト
    Lyellr88/marm-memory

    Model Context Protocol (MCP) を使用したAIエージェント向けの永続的ローカルメモリサーバー。セッション間で共有される長期記憶、コードグラフ、概念グラフを提供します。

  • プロジェクト
    AVIDS2/memorix

    A local-first shared memory layer for AI coding agents that persists project context, design decisions, and Git history across different sessions and tools.

  • Dispatch
    MCPによるコード実行：より効率的なAIエージェントの構築

    Anthropicは、AIエージェントが直接的なツール呼び出しではなく、コード実行を介してModel Context Protocol (MCP) サーバーと対話する方法を導入し、トークン消費量を削減し効率を向上させます。

  • プロジェクト
    Dicklesworthstone/mcp_agent_mail

    AIコーディングエージェント向けのメールのような調整層で、アイデンティティ、非同期メッセージング、並列作業中の競合を防ぐためのファイル予約リースを提供します。

  • プロジェクト
    oleksiijko/pmb

    PMB は、LLM ベースのコーディングアシスタントにローカルで SQLite を基盤としたメモリを提供するオープンソースの Python ライブラリです。コード、PDF、git 履歴、およびユーザーが記録した事実を自動的にインデックスし、Model-Context-Protocol を介して最も関連性の高い部分をエージェントに注入し直します。このシステムはオフラインで動作し、ハイブリッドの BM25 + ベクトル検索（ウォームレイテンシ約 35 ms）を提供し、視覚的なダッシュボードを備え、モデルが考える前にメモリを呼び出し、観察されたアクションを自動的に書き込むフックの両方を含んでいます。`pip install pmb-ai` でインストールし、`pmb setup` を実行してエージェントを接続すると、エージェントは API キーやクラウド呼び出しなしで、再起動後も決定事項、教訓、プロジェクトのコンテキストを記憶します。