完全なドキュメント -- ガイド、ツールリファレンス、アーキテクチャ、メンテナンスについては cachorro.space を参照してください。

mcp-memory

AnthropicのMCP Memoryサーバー のドロップイン代替品です。SQLiteによる永続化、ベクトル埋め込み、セマンティック検索、および動的ランキングのためのLimbic Scoringを備えています。

なぜこれが必要なのか？ 元のサーバーは、操作のたびにナレッジグラフ全体をJSONLファイルに書き込みますが、ロックやアトミックな書き込みが行われません。同時アクセス（複数のMCPクライアント）が発生すると、データ破損の原因となります。このサーバーは、それを適切なSQLiteデータベースに置き換えます。

特徴

• Anthropicの8つのMCPツールとドロップイン互換（同じAPI、同じ動作）

• SQLite + WAL -- 安全な同時アクセス、JSONLの破損を解消

• セマンティック検索 -- sqlite-vec + ONNX埋め込み（94以上の言語）

• ハイブリッド検索 (FTS5 + KNN) -- 全文検索BM25とセマンティックベクトル検索をReciprocal Rank Fusionで統合。正確な用語または意味的な類似性、あるいはその両方でエンティティを検索可能。

• Limbic Scoring -- 顕著性、時間的減衰、共起シグナル、ハイブリッド検索スコアを用いた動的再ランキング。APIに対して透過的。

• セマンティック重複排除 -- コサイン類似度が0.85以上の場合、新しい観測データに自動的に similarity_flag を付与（非対称なテキスト長に対する包含スコアリング付き）

• 統合レポート -- 分割候補、フラグ付き観測データ、古いエンティティ、大きなエンティティの読み取り専用ヘルスチェック

• 改善された時間的減衰 -- entity_access_log による追跡と ALPHA_CONS=0.2 の複数日統合シグナル

• 包含修正 -- 重複排除スコアリングにおける非対称なテキスト長（比率 >= 2.0）の適切な処理

• 観測の種類 -- 観測データのセマンティック分類（hallazgo、decision、estado、spec、metrica、metadata、generic）

• 観測の置換 -- 明示的な置換チェーン：新しい観測データが古いものを置換可能（古いものには置換済みタイムスタンプが付与される）

• エンティティステータス -- ライフサイクル追跡：activo、pausado、completado、archivado（ステータスを考慮した検索デブースト付き）

• 関係のコンテキストと有効期限 -- 関係にはオプションのコンテキスト、active/ended_at フィールドがあり、時間的な有効性を保持

• 自動逆関係 -- contains/parte_de ペアを自動作成

• リフレクション（振り返り） -- 独立したナラティブ層：エンティティ、セッション、関係、グローバルに付随する自由形式の文章。作成者と気分のメタデータ付き。セマンティック + FTS5ハイブリッド検索で検索可能

• 軽量 -- 同様のソリューションが約1.4 GBであるのに対し、合計約500 MB

• 移行 -- AnthropicのJSONL形式からワンクリックでインポート

• ゼロコンフィグ -- 箱から出してすぐに動作。セマンティック検索用のモデルダウンロードはオプション

クイックスタート

1. MCP設定に追加

{
  "mcpServers": {
    "memory": {
      "command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

または、クローンしてローカルで実行：

{
  "mcpServers": {
    "memory": {
      "command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
    }
  }
}

2. セマンティック検索を有効にする（オプション）

cd /path/to/mcp-memory
uv run python scripts/download_model.py

これにより、多言語文モデル（約465 MB）が ~/.cache/mcp-memory-v2/models/ にダウンロードされます。これがない場合でもすべてのツールは動作しますが、search_semantic は利用できません。

3. 既存データの移行（オプション）

Anthropic MCP MemoryのJSONLファイルがある場合は、migrate ツールを使用するか、直接呼び出してください：

uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"

MCPツール

コア（Anthropic互換）

検索と分析

エンティティ管理

リフレクション（振り返り）

エンティティタイプ

8つの標準タイプ：

観測の種類

観測データのセマンティック分類：

関係タイプ

4つのカテゴリ：

contiene/parte_de ペアについては、逆関係が自動作成されます。

アーキテクチャ

server.py (FastMCP)  <--  storage.py (SQLite + sqlite-vec + FTS5)
                               |
                         embeddings.py (ONNX Runtime)
                               |
                         sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
                         (384d, multilingual, cosine similarity)
                               |
                         scoring.py (Limbic Scoring + RRF)
                         salience . temporal decay . co-occurrence

• ストレージ: WALジャーナリング付きSQLite、5秒のビジータイムアウト、CASCADE削除

• 埋め込み: 起動時に一度ロードされるシングルトンONNXモデル、L2正規化コサイン検索

• Limbic Scoring: 重要度シグナル、時間的減衰、共起パターン、RRFスコアを使用してハイブリッド（KNN + FTS5）候補を再ランキング -- APIに対して透過的

• 同時実行: SQLiteが内部的にロックを処理 -- fcntlやファイルシステム競合なし

• リフレクション: ナラティブ層のための並列FTS5 (reflection_fts) およびベクトル (reflection_embeddings) インデックス。同じRRFハイブリッドパイプラインで検索

仕組み

各エンティティは、Head+Tail+Diversity選択戦略（予算：480トークン）を使用してテキストから生成された埋め込みベクトルを持ちます：

"{name} ({entity_type}) | {obs1} | {obs2} | ... | Rel: type -> target; ..."

search_semantic を呼び出すと、パイプラインが並列で実行されます：

1. セマンティック (KNN) -- クエリがエンコードされ、sqlite-vec を介してエンティティベクトルと比較されます

2. 全文検索 (FTS5) -- クエリが名前、型、観測内容をカバーするBM25インデックスに対して検索されます

3. マージ (RRF) -- 両方のブランチの結果が Reciprocal Rank Fusion (score(d) = Sum 1/(k + rank)) を使用して結合されます

マージされた候補は、Limbic Scoringエンジンによって再ランキングされます。これは以下を考慮します：

• 顕著性 -- 頻繁にアクセスされ、よく接続されているエンティティほど高くランク付けされます

• 時間的減衰 -- 最近使用されたエンティティは新鮮さを保ち、触れられていないエンティティはフェードアウトします

• 共起 -- 一緒に現れることが多いエンティティは互いを強化します

出力には limbic_score、scoring（重要度/時間的/共起の内訳）、およびFTS5が結果に寄与した場合はオプションで rrf_score が含まれます。

技術的な詳細については、DOCUMENTATION.md を参照してください。スコアリング式、RRF定数、スキーマDDL、アーキテクチャ図が含まれています。

テスト

uv run pytest tests/ -v

15個のテストファイルにわたる285以上のテストが、すべてのツール、埋め込み、スコアリング、エッジケースをカバーしています。リグレッションはゼロです。

要件

• Python >= 3.12

• uv (パッケージマネージャー)

依存関係

ライセンス

MIT