shodh-memory

Shodh-Memory MCP サーバー

AI エージェント向けの永続的な認知メモリ

ドキュメント | GitHub | Python SDK | Rust クレート

---

特長

• 認知アーキテクチャ：Cowan のモデルに基づく3階層のメモリ（作業、セッション、長期）
• ヘブ学習：「一緒に発火するニューロンは結びつく」—使用するほど関連性が強まります
• セマンティック検索：MiniLM-L6 の埋め込みを使って、意味からメモリを検索します
• ナレッジグラフ：エンティティの抽出と関係性の追跡
• メモリの統合：減衰、再生、強化を自動で行います
• 冪等性：コンテンツハッシュによる重複排除 — 同じメモリが二度保存されることはありません
• ワンクリックインストール：お使いのプラットフォーム用のネイティブサーバーバイナリを自動でダウンロードします
• オフラインファースト：初回起動時にすべてのモデルを自動でダウンロードします（合計約38MB）。以降はインターネット接続不要です
• 高速：API 応答は200ミリ秒未満、グラフ検索は1ミリ秒未満、セマンティック検索は30～50ミリ秒です
• GTD タスク管理：プロジェクト、サブタスク、コメント、リマインダーを備えた完全な ToDo システム

インストール

MCP クライアントの設定に追加します：

Claude Desktop / Claude Code（claude_desktop_config.json）：

{
  "mcpServers": {
    "shodh-memory": {
      "command": "npx",
      "args": ["-y", "@shodh/memory-mcp"],
      "env": {
        "SHODH_API_KEY": "your-api-key-here"
      }
    }
  }
}

設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

Codex CLI（.codex/config.toml）：

[mcp_servers.shodh-memory]
startup_timeout_sec = 60
command = "npx"
args = ["-y", "@shodh/memory-mcp"]
env = { SHODH_API_KEY = "your-api-key-here" }

デフォルトでは、MCP サーバーは HTTP 経由でバックエンドと通信するため、すべてのプラットフォームで動作します。通常のリクエストを認証済みのローカル IPC 経由で送信するには、プラットフォームに適した値を指定して SHODH_IPC_ENDPOINT を追加してください。Windows では、サーバーが出力するユーザーごとの名前付きパイプ（通常は \\.\pipe\shodh-memory-<current-user-SID>）を使用します。macOS/Linux では、絶対パスで指定した Unix ソケット（デフォルトでは、プラットフォームのデータディレクトリ内の shodh/shodh-memory.sock）を使用します。macOS/Linux で \\.\pipe\... を指定すると、バックエンドにそのまま転送されるのではなく、拒否されます。自動起動時には、明示的に設定したエンドポイントがバックエンドに渡されるため、両方のプロセスで同じ値が使われます。

注：初回起動時には、サーバーバイナリ（約15MB）と埋め込みモデル（約23MB）がダウンロードされます。startup_timeout_sec = 60 により、初期設定に十分な時間が確保されます。

Cursor／その他の MCP クライアントの場合：npx コマンドを使った同様の設定です。

環境変数

変数	説明	デフォルト
SHODH_API_KEY	必須。認証用の API キー	-
SHODH_IPC_ENABLED	サーバーリスナーの切り替え。この値は自動起動されたバックエンドにも適用されます。	true
SHODH_IPC_ENDPOINT	MCP リクエスト用のローカルエンドポイント：Unix ソケットパス（macOS/Linux）または \\.\pipe\name（Windows）。設定すると、通常の MCP リクエストは HTTP ではなくローカル IPC を使用します。macOS/Linux では Windows パイプの値は拒否されます。	-
SHODH_IPC_REQUIRED	IPC のバインドまたは認証ができない場合にフェイルクローズします。有効時、TypeScript クライアントにも SHODH_IPC_ENDPOINT が必要です。	false
SHODH_API_URL	バックエンドサーバーの URL	http://127.0.0.1:3030
SHODH_USER_ID	論理メモリ名前空間。認可テナントではありません	claude-code
SHODH_NO_AUTO_SPAWN	true に設定すると、バックエンドの自動起動を無効にします	false
SHODH_STREAM	ストリーミング取り込みの有効／無効を切り替えます	true
SHODH_STREAM_WEBSOCKET	IPC モードのみで、SHODH_API_URL を介した WebSocket ストリーミングを明示的に有効にします	false
SHODH_PROACTIVE	プロアクティブなメモリ表示の有効／無効を切り替えます	true

ローカル IPC

SHODH_IPC_ENDPOINT を設定すると、ツール呼び出し、プロアクティブな表示、ヘルスチェック、リソース、プロンプトはローカル IPC を使用します。各呼び出しでローカル接続を 1 つ開き、バージョン付きの改行区切り JSON リクエストとレスポンスを 1 組交換します。フレームの上限は 8 MiB です。最初に空の認証情報によるヘルスチャレンジを行い、エンドポイントが設定済みのキーを把握していることを確認します。その後、通常のリクエストではサーバーインスタンスとリクエスト本文に紐付いた HMAC 証明を使用します。再利用可能な API キーが IPC 経由で送信されたり、MCP の標準出力に書き込まれたりすることはありません。

ストリーミング取り込みは引き続き WebSocket の機能です。ローカルプロトコルが有限のリクエスト／レスポンス方式であるため、IPC モードではデフォルトで無効になっています。明示的に有効にするには、SHODH_STREAM_WEBSOCKET=true を設定し、サーバーの HTTP WebSocket エンドポイントを指すように SHODH_API_URL を設定します。通常の操作では引き続き IPC が使用されます。

SHODH_IPC_ENDPOINT が設定されていない場合、MCP サーバーは従来の HTTP および WebSocket の動作を維持します。この変数を設定すると、トランスポートが明示的に選択されます。IPC エンドポイントを利用できない場合は、HTTP による再試行を黙って行わず、その旨を報告します。

REST と同様に、SHODH_USER_ID は論理名前空間です。設定された API キーは、すべての名前空間に対する権限を持ちます。相互に信頼されていないテナント間で認可境界が必要な場合は、サーバーとキーのインスタンスを分けてください。

MCP ツール（合計 51 個）

メモリ — メモリの保存、検索、管理

ツール	説明
remember	種類、タグ、メタデータを指定してメモリを保存します
recall	関連するメモリを見つけるためのセマンティック検索です。完全な本文をインラインで取得するには、full_content: true を指定します
proactive_context	現在のコンテキストに関連するメモリを自動的に提示します。完全な本文をインラインで取得するには、full_content: true を指定します
context_summary	セッション開始時に使用する、分類されたコンテキストを取得します
list_memories	保存されているすべてのメモリを一覧表示します
read_memory	ID を指定して、特定のメモリの全文を読み取ります
forget	ID を指定して、特定のメモリを削除します

メモリのプレビューと切り詰め。 recall、recall_by_tags、proactive_context は、各メモリ本文のプレビューを返します（デフォルトの上限：500 文字）。本文が上限を超える場合、出力は、実際の文字数と後続の呼び出しを示す明示的で正確なマーカー付きで切り詰められます。例：…[truncated 500/2340 chars — read_memory("<id>") for full]。プレビューがマーカーなしでひそかに切り詰められることはありません。マーカーがなければ、本文全体が表示されています。完全な本文をインラインで取得する（マーカーなし）には、これら 3 つのツールのいずれかで full_content: true を指定します。トークン使用量が増えるため、少数の結果を取得する場合に使用してください。read_memory は常に、切り詰められていない全文を返します。

ToDo（GTD） — プロジェクトとサブタスクによるタスク管理

ツール	説明
add_todo	優先度、期限、プロジェクト、コンテキストを指定してタスクを作成します
list_todos	セマンティック検索または GTD 形式のフィルタリングで ToDo を一覧表示／検索します
update_todo	タスクのプロパティ（ステータス、優先度、メモ）を更新します
complete_todo	タスクを完了としてマークします（繰り返しタスクの場合は次のタスクを自動作成します）
delete_todo	タスクを完全に削除します
reorder_todo	ステータスグループ内でタスクを上または下に移動します
list_subtasks	親 ToDo のサブタスクを一覧表示します
add_todo_comment	タスクにコメント（進捗、解決内容）を追加します
list_todo_comments	タスクのすべてのコメントを一覧表示します
update_todo_comment	既存のコメントを編集します
delete_todo_comment	コメントを削除します
todo_stats	ステータス別の ToDo 統計と期限超過の項目を取得します

プロジェクト — ToDo をグループに整理

ツール	説明
add_project	親プロジェクト（サブプロジェクト）を任意で指定してプロジェクトを作成します
list_projects	ToDo の件数とともに、すべてのプロジェクトを一覧表示します
archive_project	プロジェクトをアーカイブします（非表示になりますが、復元可能です）
delete_project	プロジェクトを完全に削除します

リマインダー — 時刻、期間、コンテキストに応じたリマインダー

ツール	説明
set_reminder	リマインダーを設定します（時刻、期間、またはキーワードによるトリガー）
list_reminders	保留中／トリガー済み／解除済みのリマインダーを一覧表示します
dismiss_reminder	トリガーされたリマインダーを確認します

システム — ヘルスチェック、バックアップ、診断

ツール	説明
memory_stats	保存されているメモリの統計情報を取得します
verify_index	ベクトルインデックスの整合性を確認します
repair_index	孤立したメモリを再インデックスします
token_status	現在のセッションのトークン使用量を取得します
reset_token_session	新しいセッション用にトークンカウンターをリセットします
consolidation_report	メモリの統合アクティビティを表示します
backup_create	すべてのメモリのバックアップを作成します
backup_list	利用可能なバックアップを一覧表示します
backup_verify	バックアップの整合性を検証します（SHA-256）
backup_restore	バックアップから復元します
backup_purge	古いバックアップを削除し、最新の N 件を保持します

REST API（開発者向け）

サーバーは http://127.0.0.1:3030 で REST API を公開しています：

// Store a memory
const res = await fetch("http://127.0.0.1:3030/api/remember", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key"
  },
  body: JSON.stringify({
    user_id: "my-app",
    content: "User prefers dark mode",
    memory_type: "Observation",
    tags: ["preferences", "ui"]
  })
});

// Semantic search
const results = await fetch("http://127.0.0.1:3030/api/recall", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key"
  },
  body: JSON.stringify({
    user_id: "my-app",
    query: "user preferences",
    limit: 5
  })
});

主なエンドポイント

エンドポイント	メソッド	説明
/health	GET	ヘルスチェック
/api/remember	POST	メモリを保存
/api/recall	POST	セマンティック検索
/api/recall/tags	POST	タグで検索
/api/recall/date	POST	日付範囲で検索
/api/memories	POST	すべてのメモリを一覧表示
/api/memory/{id}	GET/PUT/DELETE	CRUD 操作
/api/context_summary	POST	コンテキストの要約を取得
/api/relevant	POST	コンテキストを先回りして提示
/api/batch_remember	POST	複数のメモリを保存
/api/upsert	POST	external_id に基づいて作成または更新
/api/graph/{user_id}/stats	GET	ナレッジグラフの統計情報
/api/consolidation/report	POST	メモリ統合レポート
/api/index/verify	POST	インデックスの整合性を検証
/metrics	GET	Prometheus メトリクス

認知機能

ヘッブ学習

頻繁に同時にアクセスされるメモリは、より強い関連を形成します。システムは自動的に以下を行います。

• 同時に取得されたメモリ間にエッジを形成
• 同時活性化が繰り返されると、つながりを強化
• 永続的な関連のために長期増強（LTP）を実現

メモリの統合

バックグラウンドプロセスがメモリの健全性を維持します。

• 減衰：使用されないメモリの活性度が徐々に低下します
• リプレイ：価値の高いメモリを定期的に再生します
• 刈り込み：弱い関連を削除します
• 昇格：重要なメモリを長期ストレージに移動します

3 層アーキテクチャ

Cowan のワーキングメモリモデルに基づいています。

1. ワーキングメモリ：最近の、活性度が非常に高いメモリ
2. セッションメモリ：現在のセッションのコンテキスト
3. 長期メモリ：ベクトルインデックスを備えた永続ストレージ

動作の仕組み

1. インストール：npx -y @shodh/memory-mcp でパッケージをダウンロードします
2. 自動起動：初回実行時に、ネイティブサーバーバイナリ（約 15MB）と埋め込みモデル（約 23MB）をダウンロードします
3. 接続：MCP クライアントは stdio 経由でこの MCP サーバーに接続します。バックエンドへのリクエストは、SHODH_IPC_ENDPOINT が設定されている場合はローカル IPC を使用し、それ以外の場合は HTTP を使用します
4. 準備完了：remember と recall ツールの使用を開始します
5. セッション終了：ホストが stdin を閉じると（Claude Desktop のスレッド切り替え時など）、シムは処理中のツール呼び出しを完了し、終了前に応答を開いたままの stdout に書き込みます。そのため、処理中のリクエストが通知なく破棄されることはありません。ドレイン処理には猶予時間の上限があり、時間を超えた場合は、ホストのタイムアウトまで待つ代わりに、呼び出し元に明示的なエラーが返されます。

バックエンドサーバーはローカルで実行され、すべてのデータをお使いのマシンに保存します。クラウドへの依存はありません。

使用例

"Remember that the user prefers Rust over Python for systems programming"
"Recall what I know about user's programming preferences"
"What context do you have about this project?"
"List my recent memories"
"Show me the consolidation report"

プラットフォームのサポート

プラットフォーム	アーキテクチャ	状態
Linux	x64	サポート対象
macOS	x64	サポート対象
macOS	ARM64 (M1/M2)	サポート対象
Windows	x64	サポート対象

関連パッケージ

• Python SDK：pip install shodh-memory - ネイティブ Python バインディング
• Rust クレート：cargo add shodh-memory - ライブラリとして使用

リンク

• ドキュメント
• GitHub リポジトリ
• 課題トラッカー

ライセンス

Apache-2.0