MemoryMesh

個人データのための汎用MCPハブ。ローカルファーストでデフォルトでプライベート。次に構築するエージェントのメモリ層となるように設計されています。

MemoryMeshはローカルファイルをインデックス化し（将来のバージョンではメール、カレンダー、ブラウザ履歴、チャットログにも対応予定）、Model Context Protocolを通じてそれらを公開します。MCP対応クライアント（Claude Desktop、Cursor、Claude Code、または独自のエージェント）は、データをクラウドに一切送信することなく、実際に所有しているデータに対してセマンティックな質問を行うことができます。

これは単一目的のRAGではなく、ハブです。トランスポート、埋め込みモデル、パーサー、チャンク戦略はすべてクリーンなインターフェースの背後で交換可能であり、同じハブが「メモの検索」から「エージェントOSのためのすべてを記憶する」へと成長できます。

なぜこれが存在するのか

個人データは数十ものアプリに断片化されています。AIエージェントがそのすべてに統一されたプライベートな方法でアクセスできる手段はありませんでした。AnthropicのMCPがプロトコルを定義し、MemoryMeshはそのすべてを接続するハブとしてのギャップを埋めます。設定ではなく前提条件としてプライバシーを重視し、ローカルで動作します。

Related MCP server: NOUZ MCP Server

仕組み

                   ┌──────────────────────────────┐
  MCP clients ───▶ │         MemoryMesh           │
(Claude Desktop,   │  ┌────────────────────────┐  │
 Cursor, agents)   │  │ MCP Tools (FastMCP):   │  │
                   │  │  search_memory         │  │
                   │  │  list_sources          │  │
                   │  │  get_document          │  │
                   │  │  index_now             │  │
                   │  └──────────┬─────────────┘  │
                   │             ▼                 │
                   │     Search Engine             │
                   │   dense + BM25 → RRF          │
                   │             │                 │
                   │   ┌─────────┴──────────┐      │
                   │   ▼                    ▼      │
                   │ ChromaDB            BM25      │
                   │ (embeddings)     (sparse)     │
                   │   ▲                    ▲      │
                   │   └──────── Indexer ───┘      │
                   │                ▲              │
                   │           Watchdog            │
                   └────────────────┬──────────────┘
                                    ▼
                             Your filesystem

インデックスパイプライン: ファイル監視が変更を検知 → SHA-256による重複排除で変更のないファイルをスキップ → パーサー（txt/md/pdf/docx/code） → スマートチャンカー（コードにはtree-sitter、マークダウンには見出し単位、テキストには再帰的分割） → sentence-transformersによる埋め込み → ChromaDB + BM25インデックスへのアップサート。

検索パイプライン: クエリ → dense検索（ChromaDB）+ sparse検索（BM25）のオーバーフェッチ → Reciprocal Rank Fusion (k=60) → パス、プレビュー、スコア、メタデータを含む上位k件の結果。

何が違うのか

ほとんどの類似ツールは最適化する次元を1つ選んでいます。MemoryMeshは、それらすべてを同時に満たす唯一のツールです。

MCPネイティブとは、後付けではなく最初からMCPのために構築されたことを意味します。4つのツール（search_memory、list_sources、get_document、index_now）は、バージョン間で破壊されない安定したAPIを持っています。

インフラとして設計とは、マルチエージェントアクセス、エージェントごとの権限設定、および同じハブにクエリを投げるハードウェアエージェント（ESP32、Arduinoなど）をアーキテクチャが予見していることを意味します。ロードマップを参照してください。

ステータス

クイックスタート

前提条件: Python 3.11+ および uv。

# Install from PyPI
pip install memorymesh-mcp

または開発用にクローンします：

# Clone and install
git clone https://github.com/kilhubprojects/memory-mesh.git
cd memory-mesh
uv sync

# Initialize state directory and copy example config
uv run memorymesh init

# Edit config.yaml — point it at the folders you want indexed
# (see Configuration section below)

# Index a folder
uv run memorymesh index ~/Documents

# Test a search
uv run memorymesh search "how did I configure the debounce"

デーモンとして実行（リアルタイムインデックス）

uv run memorymesh start --transport streamable-http --detach
uv run memorymesh status
# edit a file in one of your sources — it gets indexed within ~2s
uv run memorymesh search "the sentence you just typed"
uv run memorymesh stop

Claude Desktopへの組み込み

Claude Desktopの設定に追加します：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memorymesh": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/memory-mesh",
        "memorymesh", "serve", "--stdio"
      ]
    }
  }
}

Claude Desktopを再起動します。4つのツールが自動的に表示されます。

MCPツール

すべてのツールは後方互換性があります。v0.1のシグネチャは固定されており、v0.2でのextended_previewの追加は破壊的ではなく追加的なものです。

設定

すべてはconfig.yamlに記述されます。完全にコメントされたリファレンスについてはconfig.example.yamlを参照してください。主なハイライト：

sources:
  - name: documents
    path: ~/Documents
    recursive: true
    extensions: [.txt, .md, .pdf, .docx]

  - name: projects
    path: ~/Projects
    recursive: true
    extensions: [.py, .js, .ts, .go, .rs, .md]

embeddings:
  model: all-MiniLM-L6-v2   # swap to paraphrase-multilingual-MiniLM-L12-v2 for PT/EN

search:
  mode: hybrid               # hybrid | dense | sparse
  top_k: 10

server:
  transport: stdio           # stdio | streamable-http

グローバル除外リストは、デフォルトで機密パスを保護します：.env, *.key, id_rsa*, secrets/, .ssh/, .aws/, .git/, node_modules/。

ベンチマーク

ベンチマークは、v0.2が全3プラットフォームでCIを通過した後にここに公開されます。目標は「私のマシンでは速い」ではなく、再現可能な数値です。

スクリプトはすでにbenchmarks/にあり、ローカルで実行可能です：

• bench_indexing.py — 合成コーパスでのインデックススループット（チャンク/秒、MB/秒）

• bench_search_latency.py — ハイブリッド/dense/sparseモード間でのp50/p95/p99検索レイテンシ

• bench_embedding_models.py — 3つの埋め込みモデル間での速度と品質の比較

プライバシーとセキュリティ

バージョン間で変更されない3つの固いコミットメント：

1. データはマシンから一切外に出ません。 テレメトリなし。明示的にオプトインしない限り外部API呼び出しは行われず、その場合でもログにWARNINGが出力されます。

2. HTTPリスナーはデフォルトで127.0.0.1のみにバインドされます。 他のインターフェースへの公開には明示的な設定の上書きが必要です。

3. ログにはドキュメントの内容やクエリがクリアテキストで含まれることはありません。 監査ログにはクエリそのものではなく、クエリのハッシュが記録されます。

保存時の暗号化はロードマップに含まれています。OSレベルでディスクが暗号化されていれば、MemoryMeshが想定する脅威モデルに対しては十分です。

ロードマップ

詳細はROADMAP.mdを参照してください。

トラブルシューティング

• テキストファイルでUnicodeDecodeErrorが発生する — MemoryMeshはUTF-8、UTF-8 BOM、cp1252、latin-1の順で試行します。それでも失敗した場合はログに記録されてスキップされ、クラッシュはしません。

• ネットワークドライブ / WSLマウントで監視が動作しない — config.yamlでwatcher.use_polling: trueを設定してください。

• Tesseractが見つからない — システム全体にインストールし、PATHに含まれていることを確認してください。Windowsの場合: UB-Mannheim installer。

• 設定変更後に埋め込みモデルの不一致が発生する — memorymesh reindex --allを実行してください。ChromaDBに保存されたモデルIDが設定と一致しない場合、CLIは起動を拒否します。

このプロジェクトについて

MemoryMeshは、vibe coding（LLMと密接に連携して高速にコードを書く手法）を使用して構築されたソロプロジェクトであり、各フェーズで構造化されたアーキテクチャレビューを行っています。プロセス：LLMがコードを提案し、アーキテクトが正確性、設計のギャップ、仕様違反をレビューし、テストスイートが確認します。すり抜けたバグ（復旧システムの起動順序、BM25カプセル化違反、CLIでの誤ったコンストラクタkwargsなど）は、本番環境で実行される前にレビューで捕捉されました。

これが、レビューのステップを真剣に受け止めたvibe codingの姿です。172のテストスイート、本格的なハイブリッド検索パイプライン、復旧システム、そしてエージェントOSへと引き継がれるように設計されたアーキテクチャです。

貢献

MemoryMeshはまだ外部からの貢献を受け付けていません。CIや貢献ガイドはまだ整備されていません。これはv0.2で変更されます。リポジトリをウォッチするか、その頃に再度確認してください。

ライセンス

MIT。LICENSEを参照してください。

謝辞

アーキテクチャは、LlamaIndex、LangChain、PrivateGPT、AnythingLLM、MemGPT、Haystackを研究し、それぞれが何を得意とし、何を得意としないかを理解することによって形作られました。また、MCPネイティブが実際にどのようなものかを示してくれたchroma-mcpとMCP Python SDKに感謝します。