Vector Memory Mcp Server

Vector Memory MCP Server

sqlite-vec と sentence-transformers を使用する、Claude Desktop 向けのセキュアなベクトルベースのメモリーサーバーです。この MCP サーバーは、関連するコーディング経験、解決策、知識を記憶して検索することで、AI コーディングアシスタントの能力を高める永続的なセマンティックメモリー機能を提供します。

✨ 機能

• 🔍 セマンティック検索：384 次元の埋め込みを使用する、ベクトルベースの類似度検索
• 🏷️ セマンティック正規化：類似するタグの自動統合、カテゴリーの正規化、構造化されたコロン区切りタグ
• 📊 IDF タグウェイト：頻度に基づく重み付けにより、検索の関連性を向上
• 💾 永続ストレージ：sqlite-vec によるベクトルインデックスを備えた SQLite データベース
• 🔒 セキュリティ第一：入力検証、パスのサニタイズ、リソース制限
• ⚡ 高パフォーマンス：sentence-transformers による高速な埋め込み生成
• 🧹 自動クリーンアップ：インテリジェントなメモリー管理とクリーンアップツール
• 📈 豊富な統計情報：メモリーデータベースの包括的な分析
• 🔄 自動重複排除：SHA-256 コンテンツハッシュにより、メモリーの重複保存を防止
• 🧠 スマートクリーンアップアルゴリズム：新しさ、アクセスパターン、重要度に基づいてメモリーの保持を優先

🛠️ 技術スタック

コンポーネント	テクノロジー	用途
ベクトル DB	sqlite-vec	ベクトルの保存と類似度検索
埋め込み	sentence-transformers/all-MiniLM-L6-v2	384 次元のテキスト埋め込み
正規化	セマンティック類似度 + ガード	タグ／カテゴリーの自動統合
MCP フレームワーク	FastMCP	高水準のツール専用サーバー
依存関係	uv スクリプトヘッダー	自己完結型のデプロイ
セキュリティ	カスタム検証	パス／入力のサニタイズ
テスト	pytest + coverage	包括的なテストスイート

📁 プロジェクト構成

vector-memory-mcp/
├── main.py                              # Main MCP server entry point
├── README.md                            # This documentation
├── requirements.txt                     # Python dependencies
├── pyproject.toml                       # Modern Python project config
├── .python-version                      # Python version specification
├── claude-desktop-config.example.json  # Claude Desktop config example
│
├── src/                                # Core package modules
│   ├── __init__.py                    # Package initialization
│   ├── models.py                      # Data models & configuration
│   ├── security.py                    # Security validation & sanitization
│   ├── embeddings.py                  # Sentence-transformers wrapper
│   ├── memory_store.py                # SQLite-vec operations
│   ├── README_AGENTS.md               # Agent documentation (4 levels)
│   └── CASES_AGENTS.md                # Use cases for Brain ecosystem
│
└── .gitignore                         # Git exclusions

🗂️ 構成ガイド

このプロジェクトは、分かりやすく使いやすい構成になっています。

• main.py - まずはこちらから！メインサーバーのエントリーポイント
• src/ - コア実装（セキュリティ、埋め込み、メモリーストア）
• claude-desktop-config.example.json - 設定テンプレート

初めての方へ：main.py と claude-desktop-config.example.json から始めてください。

🚀 クイックスタート

前提条件

• Python 3.10 以上（推奨：3.11）
• uv パッケージマネージャー
• Claude Desktop アプリ

uv のインストール（まだインストールされていない場合）：

macOS および Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

インストールを確認：

uv --version

インストール

オプション 1：uvx で簡単にインストール（推奨）

この MCP サーバーを最も簡単に使用する方法です。クローンやセットアップは不要です！

PyPI に公開されたら、次のように直接使用できます。

# Run without installation (like npx)
uvx vector-memory-mcp --working-dir /path/to/your/project

Claude Desktop の設定（uvx を使用）：

{
  "mcpServers": {
    "vector-memory": {
      "command": "uvx",
      "args": [
        "vector-memory-mcp",
        "--working-dir",
        "/absolute/path/to/your/project",
        "--memory-limit",
        "100000"
      ]
    }
  }
}

注： --memory-limit は省略可能です。省略すると、デフォルトの 10,000 エントリーが使用されます。

注：PyPI への公開は現在進行中です。詳細は PUBLISHING.md をご覧ください。

オプション 2：ソースからインストール（開発向け）

1. プロジェクトをクローンします：

   git clone <repository-url>
   cd vector-memory-mcp
   

2. 依存関係をインストールします（uv により自動）： 依存関係は main.py 内のインラインメタデータによって自動的に管理されます。手動でインストールする必要はありません。

   依存関係を確認するには：

   uv pip list
   

3. サーバーをテストします：

   # Test with sample working directory
   uv run main.py --working-dir ./test-memory
   

4. Claude Desktop を設定します：

   サンプル設定をコピーします：

   cp claude-desktop-config.example.json ~/path/to/your/config/
   

   Claude Desktop の「設定」→「開発者」→「設定を編集」を開き、以下を追加します（パスは絶対パスに置き換えてください）。

   {
     "mcpServers": {
       "vector-memory": {
         "command": "uv",
         "args": [
           "run",
           "/absolute/path/to/vector-memory-mcp/main.py",
           "--working-dir",
           "/your/project/path",
           "--memory-limit",
           "100000"
         ]
       }
     }
   }
   

   重要：

   • 相対パスではなく、絶対パスを使用してください
   • --memory-limit は省略可能です（デフォルト：10,000）
   • 大規模なプロジェクトでは、100,000～1,000,000 を使用してください

5. Claude Desktop を再起動し、MCP 統合アイコンを確認します。

オプション 3：pipx でインストール（代替方法）

# Install globally (once published to PyPI)
pipx install vector-memory-mcp

# Run
vector-memory-mcp --working-dir /path/to/your/project

Claude Desktop の設定（pipx を使用）：

{
  "mcpServers": {
    "vector-memory": {
      "command": "vector-memory-mcp",
      "args": [
        "--working-dir",
        "/absolute/path/to/your/project",
        "--memory-limit",
        "100000"
      ]
    }
  }
}

📚 使用ガイド

利用可能なツール

1. store_memory - 知識を保存

コーディング経験、解決策、知見を保存します。

Please store this memory:
Content: "Fixed React useEffect infinite loop by adding dependency array with [userId, apiKey]. The issue was that the effect was recreating the API call function on every render."
Category: bug-fix
Tags: ["react", "useEffect", "infinite-loop", "hooks"]

2. search_memories - セマンティック検索

自然言語を使用して、関連するメモリーを検索します。

Search for: "React hook dependency issues"

3. list_recent_memories - 最近のメモリを閲覧

最近保存した内容を確認します：

Show me my 10 most recent memories

4. get_memory_stats - データベースの状態

メモリデータベースの統計情報を表示します：

Show memory database statistics

5. clear_old_memories - クリーンアップ

古くて使われていないメモリをクリーンアップします：

Clear memories older than 30 days, keep max 1000 total

6. get_by_memory_id - 特定のメモリを取得

IDを指定して、特定のメモリの詳細を取得します：

Get memory with ID 123

コンテンツ、カテゴリ、タグ、タイムスタンプ、アクセス回数、メタデータなど、すべてのフィールドを返します。

7. delete_by_memory_id - メモリを削除

特定のメモリをデータベースから完全に削除します：

Delete memory with ID 123

メタデータテーブルとベクターテーブルの両方から、メモリをアトミックに削除します。

8. get_unique_tags - すべてのタグを一覧表示

メモリで現在使用されている一意のタグをすべて取得します：

Show all unique tags

メモリのメタデータからタグを取得し、ソートして返します。

9. get_canonical_tags - 正規化されたタグを一覧表示

正規化されたタグをすべて取得します：

Show canonical tags

意味に基づく統合後の正規化済みタグを返します。タグの統合状況を把握するのに役立ちます。

10. get_tag_frequencies - タグの使用統計

正規化されたすべてのタグの出現頻度を取得します：

Show tag frequencies

各タグの使用頻度を表示します。頻度が高いほど、よく使われているタグです。

11. get_tag_weights - IDF 重み

検索の関連性を高めるための IDF ベースの重みを取得します：

Show tag weights

1 / log(1 + frequency) として計算された重みを返します：

• 一般的なタグ（api、auth）→ 重みが低い（識別力が低い）
• 珍しいタグ（module:terminal）→ 重みが高い（識別力が高い）

12. cookbook - ナレッジベース（重要）

重要：ほかのツールを使用する前に、必ず最初にお読みください。これを読まずに使用すると、状況を把握できません。

# FIRST: Initialize context (READ THIS FIRST)
mcp__vector-memory__cookbook()

# List available categories with keys
mcp__vector-memory__cookbook(include="categories")

# Cases by key (exact match)
mcp__vector-memory__cookbook(include="cases", case_category="gates-rules")
mcp__vector-memory__cookbook(include="cases", case_category="search")

# Search in cookbook
mcp__vector-memory__cookbook(include="cases", query="JWT token")
mcp__vector-memory__cookbook(include="docs", query="tag normalization", level=2)

# Pagination
mcp__vector-memory__cookbook(include="cases", query="task", limit=5, offset=0)

# Documentation by level
mcp__vector-memory__cookbook(include="docs", level=0)  # Quick start
mcp__vector-memory__cookbook(include="docs", level=2)  # Advanced patterns

# Full debug info
mcp__vector-memory__cookbook(include="all", level=3)

パラメーター：

パラメーター	値	説明
include	"init", "docs", "cases", "categories", "all"	返す内容（デフォルトは "init"）
level	0-3	ドキュメントの詳細度（デフォルトは 0）
case_category	string	キー（完全一致）またはタイトル（部分一致）でケースを絞り込みます
query	string	コンテンツをテキスト検索します
limit	1-50	最大結果数（デフォルトは 10）
offset	int	ページネーションのオフセット（デフォルトは 0）

インクルードモード：

モード	返される内容
init	最初に読む内容 — クイックスタートと利用可能なリソース
docs	レベル別のドキュメント
cases	ユースケースのシナリオ（カテゴリ／クエリで絞り込み）
categories	キーと説明を含むカテゴリ一覧
all	すべてをまとめた内容

ドキュメントレベル：

レベル	内容
0	アイデンティティとクイックスタート
1	実践的な使い方
2	高度なパターン
3	アーキテクチャと内部構造

カテゴリキー：

キー	説明
cookbook-usage	cookbook() ツールの使い方
store	重複を排除してメモリを保存
search	複数プローブ検索、タスク前のマイニング
statistics	メモリ統計、タグの出現頻度
task-management	Task MCP とのメモリ統合
brain-docs	CLI ドキュメントのインデックス化
agent-coordination	Brain による委任、マルチエージェント
integration	複数ソースのナレッジ、エラー復旧
debugging	メモリを記録しながらデバッグフローを実行
cleanup	削除操作、経過時間に基づくクリーンアップ
gates-rules	重要／高優先度のルール
task-integration	Memory-Task ワークフローパターン

**ケースカテゴリ：**Cookbook の使い方、保存、検索、統計、タスク作成、タスク分解、タスクの状態、Brain ドキュメント、エージェント連携、統合、デバッグ、クリーンアップ

**含まれる内容：**4 つのドキュメントレベル、12 のユースケースカテゴリ、Brain エコシステムのリファレンス。

メモリーのカテゴリ

カテゴリ	ユースケース
code-solution	動作するコードスニペット、実装
bug-fix	バグ修正、デバッグのアプローチ
architecture	システム設計の決定事項とパターン
learning	新しい概念、チュートリアル、知見
tool-usage	ツールの設定、CLI コマンド
debugging	デバッグ手法と発見
performance	最適化戦略とその結果
security	セキュリティ上の考慮事項と修正
other	その他すべて

🏷️ セマンティック正規化

一貫性を保つため、サーバーはセマンティック類似性を用いてタグとカテゴリを自動的に正規化します。

タグの正規化

メモリーを保存するとき、類似したタグは標準タグに統合されます。

入力タグ	標準化後
api v2.0、api 2、API version 2	api v2.0
php8、PHP 8、php-8	php8
laravel、laravel framework	laravel（部分文字列ブーストあり）

統合ルール

✅ 統合される場合：

• 同じバージョン：api v2.0 ↔ api 2（しきい値 0.85）
• 類似度が高い場合：php8 ↔ php 8（しきい値 0.90）
• 部分文字列ブースト：laravel ⊂ laravel framework（類似度 +0.03）

❌ 統合されない場合：

• バージョンが異なる：api v1 ≠ api v2
• 数値が異なる：php7 ≠ php8
• 構造化タグと通常タグ：type:refactor ≠ refactor
• 同じ接頭辞で接尾辞が異なる：type:refactor ≠ type:bug
• ストップワード：api ≠ rest api、ui ≠ web ui

構造化タグ（コロン付きタグ）

きめ細かな整理には構造化タグを使用します。

["type:refactor", "priority:high", "domain:api", "module:auth"]

使用可能な接頭辞： type、domain、strict、cognitive、batch、module、vendor、priority、scope、layer

無効な接頭辞は拒否されます：random:stuff → 削除

カテゴリの正規化

カテゴリもセマンティックに正規化されます。短い入力には辞書によるフォールバックが使用されます。

入力	出力
bugfix、bug、fix	bug-fix
auth、sec	security
perf、opt	performance
debug	debugging
arch、design	architecture

しきい値

しきい値	値	目的
タグの統合	0.90	統合に使用するデフォルトの類似度
同じバージョン	0.85	同じバージョンのタグに適用する低いしきい値
部分文字列ブースト	+0.03	部分集合となるタグへのブースト
カテゴリ	0.50	カテゴリの一致しきい値
部分文字列の最小長	4	部分文字列ブーストに必要な最小長

ストップワード（部分文字列ブーストなし）

汎用的すぎるため、これらのタグには部分文字列ブーストが適用されません。

api, ui, db, test, auth, infra, ci, cd, app, lib, sdk, cli, gui, web, sql, orm, log, cfg, env, dev, prod, stg

タグの適切な使用ガイドライン

適切なタグ（対象やドメインを表すもの）：

["authentication", "laravel", "middleware", "api v2"]

不適切なタグ（ツールや活動を表すもの）：

["phpstan", "ci", "tests", "run-migration"]  # Don't use these

IDF タグ重み

タグには IDF（逆文書頻度）を用いて重み付けされます。

weight = 1 / log(1 + frequency)

タグ	頻度	重み	説明
api	50	0.26	非常に一般的で、識別力が低い
laravel	10	0.43	一般的で、識別力は中程度
module:terminal	2	1.44	稀で、識別力が高い

すべての重みを確認するには get_tag_weights を使用します。稀なタグは、一般的なタグよりも検索の関連性を高めます。

🔧 設定

コマンドライン引数

サーバーは次の引数に対応しています。

# Run with uv (recommended) - default 10,000 memory limit
uv run main.py --working-dir /path/to/project

# With custom memory limit for large projects
uv run main.py --working-dir /path/to/project --memory-limit 100000

# Working directory is where memory database will be stored
uv run main.py --working-dir ~/projects/my-project --memory-limit 500000

使用可能なオプション：

• --working-dir（必須）：メモリーデータベースの保存先ディレクトリ
• --memory-limit（任意）：メモリーエントリーの最大数
  • デフォルト：10,000 エントリー
  • 最小：1,000 エントリー
  • 最大：10,000,000 エントリー
  • 大規模プロジェクトでの推奨値：100,000～1,000,000

作業ディレクトリの構造

your-project/
├── memory/
│   └── vector_memory.db    # SQLite database with vectors
├── src/                    # Your project files
└── other-files...

セキュリティ制限

• メモリー内容の最大長：10,000 文字
• メモリーの最大合計数：--memory-limit で設定可能（デフォルト：10,000 エントリー）
• 検索結果の最大数：クエリあたり 50 件
• メモリーあたりのタグの最大数：10 個
• パス検証：不審な文字をブロック

🎯 ユースケース

個人開発者向け

# Store a useful code pattern
"Implemented JWT refresh token logic using axios interceptors"

# Store a debugging discovery  
"Memory leak in React was caused by missing cleanup in useEffect"

# Store architecture decisions
"Chose Redux Toolkit over Context API for complex state management because..."

チームのワークフロー向け

# Store team conventions
"Team coding style: always use async/await instead of .then() chains"

# Store deployment procedures
"Production deployment requires running migration scripts before code deploy"

# Store infrastructure knowledge
"AWS RDS connection pooling settings for high-traffic applications"

学習と成長のために

# Store learning insights
"Understanding JavaScript closures: inner functions have access to outer scope"

# Store performance discoveries
"Using React.memo reduced re-renders by 60% in the dashboard component"

# Store security learnings
"OWASP Top 10: Always sanitize user input to prevent XSS attacks"

🔍 セマンティック検索の仕組み

サーバーは sentence-transformers を使用して、記憶を意味を捉える384次元ベクトルに変換します。

検索例

クエリ	見つかる記憶
"authentication patterns"	JWT、OAuth、ログインシステム、セッション管理
"database performance"	SQL 最適化、インデックス作成、クエリ調整、キャッシュ
"React state management"	useState、Redux、Context API、状態管理パターン
"API error handling"	HTTP ステータスコード、再試行ロジック、エラーレスポンス

類似度スコア

• 0.9以上：非常に関連性が高く、ほぼ完全に一致します
• 0.8〜0.9：関連性が高く、意味的に強く類似しています
• 0.7〜0.8：中程度に関連性があり、文脈によく合致します
• 0.6〜0.7：ある程度関連性があり、役立つ可能性があります
• 0.6未満：関連性が低く、おそらく役に立ちません

📊 データベース統計

get_memory_stats ツールで、包括的な分析情報を確認できます。

{
  "total_memories": 247,
  "memory_limit": 100000,
  "usage_percentage": 0.25,
  "categories": {
    "code-solution": 89,
    "bug-fix": 67,
    "learning": 45,
    "architecture": 23,
    "debugging": 18,
    "other": 5
  },
  "recent_week_count": 12,
  "database_size_mb": 15.7,
  "health_status": "Healthy"
}

統計フィールドの説明

• total_memories：データベースに保存されている現在の記憶数
• memory_limit：許可される記憶の最大数（--memory-limit で設定可能。デフォルト：10,000）
• usage_percentage：データベース容量の使用率（total_memories / memory_limit * 100）
• categories：カテゴリ種別ごとの記憶数の内訳
• recent_week_count：過去7日間に作成された記憶数
• database_size_mb：ディスク上にある SQLite データベースファイルの物理サイズ
• health_status：使用状況とパフォーマンス指標に基づく、データベース全体の健全性を示す指標

🛡️ セキュリティ機能

入力の検証

• インジェクション攻撃を防ぐため、すべてのユーザー入力をサニタイズします
• 制御文字とヌルバイトを削除します
• すべてのコンテンツに長さ制限を適用します

パスのセキュリティ

• すべてのファイルパスを検証し、正規化します
• ディレクトリトラバーサル攻撃を防ぎます
• 不審な文字パターンをブロックします

リソース制限

• 記憶の総数と個々の記憶のサイズを制限します
• データベースの肥大化とメモリ枯渇を防ぎます
• 古いデータを対象としたクリーンアップ機能を実装しています

SQL の安全性

• パラメーター化クエリのみを使用します
• ユーザー入力から動的に SQL を構築しません
• 安全な同時アクセスのために SQLite WAL モードを使用します

🔧 トラブルシューティング

よくある問題

サーバーが起動しない

# Check if uv is installed
uv --version

# Test server manually
uv run main.py --working-dir ./test

# Check Python version
python --version  # Should be 3.10+

Claude Desktop が接続しない

1. 設定内の絶対パスを確認します
2. Claude Desktop のログを確認します：~/Library/Logs/Claude/
3. 設定を変更した後、Claude Desktop を再起動します
4. Claude を設定する前に、サーバーを手動でテストします

記憶の検索が機能しない

• sentence-transformers モデルが正常にダウンロードされたことを確認します
• memory/ ディレクトリ内のデータベースファイルのアクセス権を確認します
• より幅広い検索語を試します
• 関連性を確認するため、記憶の内容を見直します

パフォーマンスの問題

• get_memory_stats を実行してデータベースの健全性を確認します
• clear_old_memories を使用して古いエントリを整理します
• 埋め込み生成に必要なハードウェアリソースを増やすことを検討します

デバッグモード

詳細なログを確認するには、サーバーを手動で実行します。

uv run main.py --working-dir ./debug-test

🚀 高度な使い方

記憶の一括保存

Claude Desktop のインターフェースからツールを複数回呼び出して、関連する複数の記憶を保存します。

記憶を整理する方法

プロジェクト別

タグを使ってプロジェクトごとに整理します。

• ["project-alpha", "frontend", "react"]
• ["project-beta", "backend", "node"]
• ["project-gamma", "devops", "docker"]

技術スタック別

• ["javascript", "react", "hooks"]
• ["python", "django", "orm"]
• ["aws", "lambda", "serverless"]

問題領域別

• ["authentication", "security", "jwt"]
• ["performance", "optimization", "caching"]
• ["testing", "unit-tests", "mocking"]

開発ワークフローとの統合

コードレビューからの学び

"Code review insight: Extract validation logic into separate functions for better testability and reusability"

スプリントの振り返り

"Sprint retrospective: Using feature flags reduced deployment risk and enabled faster rollbacks"

技術的負債の追跡

"Technical debt: UserService class has grown too large, needs refactoring into smaller domain-specific services"

📈 パフォーマンスベンチマーク

さまざまなデータセットサイズでのテストに基づいています。

メモリ数	検索時間	ストレージサイズ	RAM 使用量
1,000	<50ms	~5MB	~100MB
5,000	<100ms	~20MB	~200MB
10,000	<200ms	~40MB	~300MB

sentence-transformers/all-MiniLM-L6-v2 を使用し、MacBook Air M1 でテスト

🔧 高度な実装の詳細

データベースインデックス

メモリストアでは、パフォーマンス向上のために最適化された 4 つのインデックスを使用します。

1. idx_category：カテゴリベースのフィルタリングと統計処理を高速化します
2. idx_created_at：時間ベースのクエリと最近のメモリの取得を最適化します
3. idx_content_hash：SHA-256 ハッシュ検索により、高速な重複チェックを実現します
4. idx_access_count：使用パターンを追跡し、クリーンアップアルゴリズムの効率を向上させます

重複排除システム

コンテンツの重複排除には SHA-256 ハッシュを使用し、同一のメモリが保存されないようにします。

• 正規化したコンテンツ（前後の空白を削除し、小文字に変換）からハッシュを計算します
• 挿入前にチェックを実行します
• 重複した場合は、既存のメモリ ID を返します
• ストレージのオーバーヘッドを減らし、データ品質を維持します

アクセスの追跡

各メモリの使用状況を追跡し、インテリジェントな管理に活用します。

• access_count：検索または直接アクセスによってメモリが取得された回数
• last_accessed_at：最後にアクセスされた日時
• created_at：作成時の日時
• クリーンアップアルゴリズムでは、価値のあるメモリと古くなったメモリの特定に使用します

クリーンアップアルゴリズム

スマートクリーンアップでは、複数の要素に基づいてメモリの保持を優先します。

1. 新しさ：古いメモリより新しいメモリを優先します
2. アクセスパターン：頻繁にアクセスされるメモリを保護します
3. 経過期間のしきい値：設定可能な days_old パラメーターにより、明確な期限を設けます
4. 件数制限：価値の低い項目を削除して max_memories の上限を維持します
5. スコアリングシステム：access_count と新しさを組み合わせて、保持するメモリを決定します

🤝 貢献

これは、個人またはチームでの使用を目的としたスタンドアロンの MCP サーバーです。改善に取り組む場合は、次の手順に従ってください。

1. リポジトリをフォークします
2. ユースケースに合わせて必要な変更を加えます
3. 独自の要件に沿って十分にテストします
4. プルリクエストを通じて改善内容を共有します

📄 ライセンス

このプロジェクトは MIT License のもとで公開されています。

🙏 謝辞

• sqlite-vec：Alex Garcia による優れた SQLite ベクター拡張機能
• sentence-transformers：Nils Reimers によるセマンティック埋め込みライブラリ
• FastMCP：Anthropic による高レベル MCP フレームワーク
• Claude Desktop：MCP 統合プラットフォームの提供

---

専用のベクターデータベースの複雑さを伴わずに、永続的な AI メモリを利用したい開発者のために構築されています。