memory-fts

claude-memory-fts

Claude Code 用の長期記憶 MCP サーバーです。事実をローカルの SQLite データベースに保存し、ハイブリッド検索（FTS5 ＋ セマンティックベクトル類似度）とコンテキストの自動注入を行います。

特長

• ハイブリッド検索 — FTS5 によるキーワード検索とセマンティックベクトル類似度検索を行い、逆順位融合（RRF）で統合します
• 意味理解 — キーワードだけでなく意味から記憶を検索できます（all-MiniLM-L6-v2 の埋め込みを利用）
• コンテキストの自動注入 — 重要度が最も高い上位 30 件の記憶を、フック経由ですべてのプロンプトに注入します
• 重要度によるランキング — アクセス頻度、経過時間による減衰、カテゴリの重みをもとに事実をランク付けします
• アクセス追跡 — 各記憶へのアクセス頻度を追跡します
• アップサート — 既存の事実を重複させず、自動的に更新します
• カテゴリ分類 — preference、decision、technical、project、workflow、personal、general の種類ごとに整理します
• MCP リソース — セッションコンテキスト用の memory://context リソースを公開します
• 設定不要 — インストール後すぐに使え、データは ~/.claude/memory.db に保存されます

インストール

# Add to Claude Code
claude mcp add memory -- npx claude-memory-fts

# Auto-configure context injection hook (recommended)
npx claude-memory-fts --setup-hook

--setup-hook コマンドは、次の処理を自動的に行います。

1. ~/.claude/scripts/memory-context.sh を作成します
2. ~/.claude/settings.json に UserPromptSubmit フックを追加します
3. 上位 30 件の記憶がすべてのプロンプトに自動的に注入されます

CLI コマンド

コマンド	説明
npx claude-memory-fts	MCP サーバーを起動します（Claude Code が使用）
npx claude-memory-fts --context	上位 30 件の事実を出力します（フックスクリプトが使用）
npx claude-memory-fts --setup-hook	コンテキスト注入フックを自動設定します

設定

環境変数	デフォルト	説明
MEMORY_DB_PATH	~/.claude/memory.db	SQLite データベースファイルのパス

カスタムパスを指定する例：

claude mcp add memory -e MEMORY_DB_PATH=/path/to/my/memory.db -- npx claude-memory-fts

ツール

memory_save

事実を長期記憶に保存します。

パラメーター	型	必須	説明
fact	string	はい	記憶する情報
category	string	いいえ	次のいずれか：preference、decision、personal、technical、project、workflow、general

memory_search

ハイブリッド検索を行います。FTS5 検索とセマンティック検索を並列で実行し、結果を RRF で統合します。一部一致の場合は LIKE にフォールバックします。

パラメーター	型	必須	説明
keyword	string	はい	検索するキーワードまたは語句
limit	number	いいえ	最大結果数（デフォルト：10）

memory_update

ID を指定して、記憶の内容またはカテゴリを更新します。

パラメーター	型	必須	説明
id	number	はい	記憶 ID
fact	string	いいえ	新しい内容（現在の内容を保持する場合は省略）
category	string	いいえ	新しいカテゴリ（現在のカテゴリを保持する場合は省略）

memory_list

保存されているすべての記憶を、カテゴリ別にまとめて一覧表示します。

パラメーター	型	必須	説明
category	string	いいえ	カテゴリで絞り込みます
limit	number	いいえ	最大結果数（デフォルト：50）

memory_delete

ID を指定して記憶を削除します。

パラメーター	型	必須	説明
id	number	はい	記憶 ID

リソース

memory://context

重要度スコアに基づいてランク付けされた上位 30 件の事実を公開する MCP リソースです。

• アクセス頻度 — 頻繁にアクセスされる事実ほどスコアが高くなります（上限 20 ポイント）
• 新しさ — 最近更新された事実ほどスコアが高くなります（10 ポイント。90 日間で減衰）
• カテゴリの重み — preference／decision（3）、workflow／technical（2）、project／personal（1）、general（0）

仕組み

検索パイプライン

1. FTS5 ＋ BM25 と セマンティックベクトル類似度検索を並列で実行します
2. 逆順位融合（k=60）を使って結果を統合し、重複を除去します
3. 両方のリストに含まれる事実は、自動的にスコアが加算されます
4. どちらの検索結果も空の場合は、部分文字列を照合する LIKE にフォールバックします
5. 検索結果に含まれるたびにアクセス数を記録します

埋め込み

• モデル：all-MiniLM-L6-v2（384 次元、約 23MB）
• @xenova/transformers を使用してローカルで生成します。API 呼び出しは不要で、データがマシンの外部に送信されることはありません
• 埋め込みは保存時に作成され、サーバー起動時に既存データにも適用されます
• ノイズを除外するため、しきい値 0.3 のコサイン類似度を使用します

ストレージ

• 高速な同時読み書きのために、WAL モードの SQLite を使用します
• FTS5 仮想テーブルはトリガーで同期され、リアルタイムの全文インデックス作成に対応します
• 埋め込みは、ファクトと並んで BLOB 列に保存されます

開発

git clone https://github.com/kurovu146/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build
npm test

ライセンス

MIT