N3MemoryCore Lite (Working Memory)

N3MemoryCore MCP — Lite（エフェメラル）

N3MC-MCP-Lite は、Claude Code、Cursor、Windsurf などの MCP 対応エディターで使用する「外部メモリーサーバー」です。 MCP サーバーとして動作し、AI がセッションをまたいで会話やコードのコンテキストを保存・検索できます。

NeuralNexusNote™ の製品 — 無料の Lite ビルドです。Redis Stack を基盤とし、各エントリーの TTL が 7 日間に設定された、エフェメラルなハイブリッド（ベクトル＋BM25）メモリーを Model Context Protocol サーバーとして提供します。

💬 MCP プロトコルでは、LLM に save_memory の呼び出しを促すことしかできないため、実際に保存される会話は最終的に LLM 次第です。ただし、Claude Code に頼めば、フックを使ってすべての会話を自動保存する設定もできます。 「各ターンの後に、Claude Code のトランスクリプト全体を Lite に自動保存して」と伝えるだけで、Claude Code が ~/.claude/hooks/ にスクリプトを配置し、~/.claude/settings.json に Stop フックを追加します。 ハーネスがフックを確実に実行するため、LLM が save_memory の呼び出しを覚えているかどうかには依存せず、Claude が誤って保存をスキップすることはありません。詳しくは、以下のフックを使ったトランスクリプト全体の保存セクションをご覧ください。

🇯🇵 日本語版はこちら 🛡️ 開発方針

---

🚀 クイックスタート — 3 ステップで Claude Code に接続

「何もインストールされていない状態」から「Claude Code が N3MC メモリーを使用している状態」まで、最速で設定できます。自分に合ったインストール方法（PyPI／フォーク／uvx）を選び、クライアント設定にサーバーを追加してください。Claude Code CLI と Claude Desktop の両方に対応しています。

ステップ 1 — Redis Stack を起動

docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
# (Subsequent sessions: `docker start redis-stack`)

ステップ 2 — パッケージをインストール（いずれかを選択）

最速の方法 — Claude Code マーケットプレイス。 2 つのコマンドでインストールと MCP 接続の設定をまとめて行えます。Claude Code 内で実行してください。

/plugin marketplace add NeuralNexusNote/n3mcmcp-lite
/plugin install n3mc-workingmemory@neuralnexusnote

次に /reload-plugins を実行し、ステップ 3 はスキップしてください。プラグインマニフェストが MCP 接続を設定します。以下の手動オプションは、フォーク、カスタム設定、Claude Desktop でも引き続き利用できます。

---

（a）PyPI から — ほとんどのユーザー向け：

pip install n3memorycore-mcp-lite

（b）フォークから（このリポジトリをクローンした場合） — コントリビューター／カスタマイズする方向け：

git clone https://github.com/<YOU>/n3mcmcp-lite
cd n3mcmcp-lite
pip install -e ".[dev]"

（c）uvx でインストール不要 — グローバルインストールなしで、隔離された環境を使用：

# Just verify it runs; the actual launch is handled by your MCP client config:
uvx --from n3memorycore-mcp-lite n3mc-workingmemory --help

ステップ 2 の後、n3mc-workingmemory コマンドが PATH 上で利用できるようになります。where n3mc-workingmemory（Windows）または which n3mc-workingmemory（macOS/Linux）を実行して確認してください。

ステップ 3 — MCP クライアントに接続

クライアント	設定方法
Claude Code（CLI）、このリポジトリの作業ツリー	.mcp.json はすでにコミットされています。リポジトリに cd して claude を実行するだけです。CLI は次のプロンプトで自動接続します。
Claude Code（CLI）、別のプロジェクトディレクトリ	.mcp.json をそのプロジェクトにコピーするか、同じ n3mc-workingmemory ブロックをそのプロジェクトの .mcp.json に追加してください。Claude Code（スタンドアロン CLI）をご覧ください。
Claude Desktop（組み込みの「Code」タブを含む）	claude_desktop_config.json を編集します（パスは OS によって異なります）。Claude Desktopをご覧ください。
ツールの自動承認を有効にした Claude Code	「許可しますか？」というプロンプトで AI が止まらないように、~/.claude/settings.json にブロックを 1 つ追加します。ツール呼び出しの自動承認をご覧ください。
uvx で起動（グローバルインストール不要）	クライアント設定で、uvx 形式の command／args を使用してください。Claude Code（スタンドアロン CLI）をご覧ください。

これで完了です。Claude Code を接続すると、サーバーの動作指示が適用され、各ターンの開始時に search_memory が実行され、意味のあるやり取りの後に save_memory が自動実行されます。

初回の呼び出しのみ、最初は 30～60 秒かかることがあります。約 400 MB の intfloat/multilingual-e5-base 埋め込みモデルが ~/.cache/huggingface/ にダウンロードされます。次回以降の起動は数秒で完了します。

---

⚠️ 前提条件（インストール前に必須）

このサーバーはそのままでは動作しません。まず、以下の2つを準備する必要があります。

1. localhost:6379 の Redis Stack — Lite ビルドは Redis + RediSearch にメモリを保存します。最も簡単な方法は Docker です。

   # First time only (creates the container):
   docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
   
   # Every subsequent session (container already exists):
   docker start redis-stack
   

   コンテナーの作成後に docker run コマンドを再実行すると、Conflict. The container name "/redis-stack" is already in use エラーが発生します。2回目以降のセッションでは docker start を使用してください。

   docker の行に永続化フラグがない理由：このビルドは 意図的に揮発性に設計されています。一時性は設計上の機能であり、 機能の欠如ではありません。詳しくは、以下の「ユースケース」セクションを ご覧ください。壊れやすいシェルのクォートに頼って --save "" を 指定するのではなく（Windows PowerShell と cmd.exe では動作しません）、 MCP サーバーは接続のたびに CONFIG SET appendonly no と CONFIG SET save "" を実行して、起動時に一時的な状態を強制します。 セッション間に手動で永続化を再度有効にしても、次回の Lite 実行時に 元に戻ります。上記の通常の docker run で十分です。一時性の保証に 関する信頼できる情報源はサーバーです。

2. PATH 上の uv — Claude Code プラグイン／uvx インストール経路でのみ必要です。ソースからインストールする場合は不要です。

Redis に接続できない場合、サーバーは起動を拒否します。また、uv がないと Claude Code プラグインは起動に失敗します。/plugin install を実行する前、またはクライアント側の設定を行う前に、両方をインストールしてください。

---

機能

• 💾 完全にローカル — 会話は独自の Redis インスタンス内に保持されます。クラウドに送信されるものはありません。
• 🔍 セマンティック検索 — 正確な単語が異なっていても、過去の関連する会話を見つけます。
• 🌐 初期状態で多言語に対応 — CPU のみで動作し、LLM／GPU は不要です。NFKC 正規化（ｱﾙﾌｧ↔アルファ、１２３↔123、合字）、日本語／中国語／韓国語／タイ語／ラオス語／ミャンマー語／クメール語のバイグラム対応、ラテン文字の発音区別符号の相互照合（café↔cafe）に対応しています。
• 🛡️ エンコーディングの安全性 — Windows では stdio の UTF-8 を再設定（cp932 → UTF-8）し、すべての入力で孤立サロゲートをサニタイズします。Free ビルドと同じ保護機能です。
• 🔄 セッションをまたぐコンテキスト — 7日間保持される作業メモリです（Redis TTL により自動的に期限切れになります。より長く保持する必要がある場合は、永続メモリバックエンドと組み合わせてください）。
• ⚡ 自動で動作 — 保存と検索は自動で行われます。MCP initialize レスポンスに動作指示が含まれているため、ユーザーによる操作は必要ありません。
• 🤖 マルチエージェントに対応 — 複数の AI エージェントが1つの Redis を共有します。b_local と b_session のバイアスにより、チーム全体の知識も提示しながら、各プロジェクト独自のメモリが優先されます。
• 🏢 チームおよび組織をサポート — Redis を共有サーバーにデプロイし、N3MC_REDIS_URL をそのサーバーに設定すれば、チーム全体でメモリを共有できます（⚠️ 認証は Redis レイヤーで処理する必要があります）。
• 🧹 一時性は設計上の機能 — 7日後に自動的に期限切れになるため、失敗した試行や放棄された設計が次のタスクに持ち越されません。docker restart redis-stack を実行すると、すべてを即座に消去できます。
• 💰 トークンの無駄を削減 — 過去のコンテキストを何度も説明する必要がなくなります。メモリ検索にはローカルの埋め込みモデル（intfloat/multilingual-e5-base）を使用するため、Claude のトークンを消費しません。また、正確なコンテキスト注入により、修正ややり取りの往復も減ります。

仕組み

User's message
    │
    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  1. Auto-save │────▶│ 2. Semantic   │────▶│ 3. Context    │
│  Save last    │     │    search     │     │    injection   │
│  response to  │     │  Find related │     │  Feed to       │
│  Redis        │     │  memories     │     │  Claude        │
└──────────────┘     └──────────────┘     └──────────────┘
                                                 │
                                                 ▼
                                          Claude responds
                                          with full context

すべては MCP initialize レスポンスに含まれる動作指示によって自動的に実行されます。Claude Code のフックは関与しません。クライアント側で必要な設定は、ツールを permissions.allow に追加することだけです。ユーザーによる操作は必要ありません。

Claude の組み込み自動メモリとの関係

Claude Code には、組み込みの自動メモリシステム（~/.claude/projects/.../memory/）があります。N3MemoryCore はこれと競合するのではなく、補完するものです。

	Claude の自動メモリ	N3MemoryCore RAG
強み	信頼性が高く、毎回のセッションで読み込まれ、固定情報に最適です	会話の文脈、詳細な履歴
弱み	会話の流れや文脈を捉えられません	検索品質に依存し、必ず結果に表示されるとは限りません
最適な用途	ユーザープロファイル、フォルダーのパス、安定した設定	会話のスレッド、過去の決定、推論

推奨される使い方：

• 毎回のセッションで必要な固定情報（フォルダーのパス、ユーザーの設定）→ 自動メモリに保存します
• 会話の文脈と履歴（議論のスレッド、過去の決定）→ N3MemoryCore が自動的に蓄積します（7 日間のウィンドウ。より長く保持する必要がある場合は、永続メモリバックエンドと組み合わせてください）

---

ユースケース — ワーキングメモリが適している場面

7 日間の TTL と揮発性の Redis ストレージは、制限ではなく設計上の特長です。このサーバーは、次のような用途に適しています。

• エージェント型のコード生成ループ — 失敗した試行や放棄した設計が次のタスクに影響しません。docker restart redis-stack を実行すれば、メモリを一掃できます。
• マルチエージェントのコラボレーション — あるタスクでの決定が、無関係な後続タスクに混入しません。
• 実験的な使い捨てプロトタイピング — そのままにしておけば、メモリは 7 日後に消去されるため、整理は不要です。
• プロジェクト単位のワーキングメモリ — タスクやプロジェクトごとに session_id を固定して、コンテキストを明確に分離できます。

数か月から数年にわたる長期的かつ永続的な知識の蓄積が必要な場合、ワーキングメモリは適切なレイヤーではありません。このサーバーを、公式のナレッジグラフサーバー、独自の SQLite ベースの実装、外部サービスなど、任意の永続メモリ MCP と組み合わせて、長期的な用途をカバーしてください。

これは何ですか？

n3memorycore-mcp-lite は、Claude（およびその他の MCP 対応クライアント）に、会話をまたいで短期間のメモリを提供するローカル専用の MCP サーバーです。ローカルの Redis Stack インスタンスにテキストエントリーを保存し、BM25 全文インデックスと 768 次元のベクトルインデックス（intfloat/multilingual-e5-base）の両方を使用して、ハイブリッドランキングの結果を返します。

すべての操作はユーザーのマシン上で実行されます。API 呼び出しも、クラウドストレージもありません。

提供するツール

ツール	目的
search_memory	ハイブリッド（ベクトル + BM25）検索。ランキングと時間減衰を適用し、session_id を優先します
save_memory	短いエントリーを保存します（TTL は 7 日間。完全一致と近似重複を重複として除外します）
list_memories	新しいものから順に、最新のエントリーを一覧表示します
delete_memory	ID を指定して特定のエントリーを削除します（ID が親ドキュメントの場合、チャンクも連動して削除します）
delete_memories_by_session	session_id に関連付けられたすべてのメモリを一括削除します — 完了したプロジェクトの後片付けに使えます
repair_memory	RediSearch インデックスが見つからない場合に再作成します

このサーバーは、MCP の initialize レスポンスを通じて動作指示も提供します。毎回のターンの開始時に search_memory を、意味のあるやり取りの後に save_memory を実行するようクライアントに求めるため、Claude Code のフックを使わずに「自動保存」を維持できます。

ID の階層

N3MemoryCore は、5 つの ID フィールドを使って、各レコードの出所とコンテキストを識別します。ほとんどのユーザーが操作するのは session_id だけです（agent_name を操作することもまれにあります）。その他のフィールドは自動的に設定されます。

ID	保存先	生成タイミング	粒度	用途
id (PK)	Redis hash	レコードごと（UUIDv7、時系列順）	1 レコード	各メモリの一意の識別子です。delete_memory と重複排除に使用されます。
owner_id	config.json	初回起動時（UUIDv4）	所有者／インストール	データの所有者を識別します。各 save_memory で検証され、不一致のペイロードは owner_id mismatch として拒否されます。TAG フィールドとして保存されます。フィルタリングは Python で行われます（仕様 §3.12 を参照）。
local_id (agent_id)	config.json	初回起動時（UUIDv4）	エージェント／インストール	このインストールを識別する UUIDv4 です。将来の永続化方式との互換性を確保するため、すべての行に保存されます。ただし、Lite の b_local ランキングには使用されません。b_local は stored_importance + access_count のみから計算されます（ランキング計算式を参照）。
session_id	メモリ内、またはクライアントから指定	タスク／プロジェクト／会話ごと（文字列）	タスク／プロジェクト／会話	同じタスク／プロジェクトのメモリをまとめて表示します。b_session のランキングバイアス（b_session_match=1.0、b_session_mismatch=0.6）を制御するため、同じ Redis インスタンス内の無関係な別プロジェクトの行より、現在のチャットのメモリが優先されます。また、delete_memories_by_session のフィルターキーとしても使われます。解決順序：呼び出しごとの引数 → N3MC_SESSION_ID 環境変数 → プロセスごとの UUIDv4 フォールバック。
agent_name	Redis hash	save_memory の呼び出しごと（任意の文字列）	エージェントの表示ラベル	人が読み取れるラベル（例："claude-code"、"claude-desktop"）です。ランキングには使用されず、表示／監査のみに使われます。

owner_id  (one N3MC server / data owner)
  └── session_id  (one task / project / conversation)
        └── local_id  (the agent speaking inside that session)
              ├── agent_name  (its display name: "claude-code" etc.)
              └── id  (one memory record)

実用上のガイダンス：

• 名前の付いたプロジェクトやタスクで作業する場合は、session_id を固定してください。同じ文字列（例："proj-alpha"、"task-refactor-auth"）を save_memory と search_memory の両方に渡します。これにより、プロジェクト固有のメモリのランキングが上がるだけでなく、プロジェクト終了時に delete_memories_by_session を一度呼び出すだけで削除できます。
• 単一エージェントで使う場合は、agent_name を空のままにできます。複数のエージェントで同じ Redis を共有する場合は、監査／一覧の出力を読みやすく保てるよう、"claude-code"、"cursor" などを設定してください。
• 所有権を証明する必要がある場合を除き、owner_id は渡さないでください。サーバーは config.json と照合して検証し、不一致を拒否します。空の値は「自分のものを使う」という意味です。

前提条件

1. Redis Stack を起動する

Lite ビルドには Redis Stack（Redis + RediSearch モジュール）が必要です。最も簡単な方法は Docker です。

# First time only (creates the container):
docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest

# Every subsequent session (container already exists):
docker start redis-stack

これで完了です。コンテナーは Redis を localhost:6379 で公開し、サーバーが自動的に検出します。初回インストール後に docker run コマンドを再実行すると、Conflict. The container name "/redis-stack" is already in use と表示されます。それ以降は docker start redis-stack を使用してください。

2. パッケージをインストールする

PyPI からインストールする（推奨）：

pip install n3memorycore-mcp-lite

または、uvx を使ってインストールせずに実行できます（Claude Code プラグインではこの方法を使用します）。

uvx --from n3memorycore-mcp-lite n3mc-workingmemory

ソースからインストールする（コードを編集する場合）：

git clone https://github.com/NeuralNexusNote/n3mcmcp-lite
cd n3mcmcp-lite
pip install -e .

初回実行時に Hugging Face から約 400 MB の埋め込みモデルがダウンロードされ、標準の ~/.cache/huggingface/ ディレクトリに保存されます。

初回インストールでは、次の 3 つのリソースへのインターネット接続が必要です。

1. github.com — /plugin marketplace add NeuralNexusNote/n3mcmcp-lite でプラグインを登録するとき（代わりに uvx またはソースからインストールする場合は、この手順を省略してください）。
2. pypi.org — uvx --from n3memorycore-mcp-lite（または pip install）でパッケージを解決するとき。
3. huggingface.co — サーバーの初回起動時に intfloat/multilingual-e5-base（約 400 MB）をダウンロードし、~/.cache/huggingface/ に保存するとき。

オフラインの場合、3 つのリソースはいずれも時間制限付きの明示的なエラーを返すため、処理が停止することはありません。2 回目以降の起動ではローカルキャッシュのみを使用し、インターネット接続は不要です。

クライアントを設定する

Claude Desktop（および Claude Desktop 内の「Code」タブ）

Claude Desktop アプリケーション（組み込みの Code タブを含みます）を使用している場合は、.mcp.json（単体の claude CLI でのみ読み込まれます）ではなく、デスクトップの設定ファイルで MCP を設定してください。

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "n3mc-workingmemory": {
      "command": "n3mc-workingmemory",
      "args": []
    }
  }
}

Windows のヒント： 上記のコマンド名だけでは Claude Desktop がサーバーを起動できない場合（ハンマー／ツールのアイコンが表示されない場合）は、"command" をインストール済み .exe の絶対パスに置き換えてください。例：

"command": "C:\\Users\\<YOU>\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\n3mc-workingmemory.exe"

ターミナルで where n3mc-workingmemory を実行すると、お使いのマシン上の正確なパスを確認できます。

設定ファイルを編集した後は、Claude Desktop を完全に終了してください。 ウィンドウを閉じるだけでは不十分です。システムトレイの Claude アイコンを右クリックするか、タスクマネージャーを使ってすべての Claude プロセスを終了し、その後再起動してください。

Claude Code（単体の CLI）

このセクションは claude コマンドラインツールのみに適用されます。Claude Desktop の「Code」タブには適用されません（上記を参照してください）。

このリポジトリには .mcp.json がすでに含まれています。 リポジトリをクローンしてパッケージをインストールすると、Claude Code CLI が自動的に接続されるため、手動での設定は不要です。

他のプロジェクトでは、そのプロジェクトの .mcp.json に以下を追加してください。

{
  "mcpServers": {
    "n3mc-workingmemory": {
      "type": "stdio",
      "command": "n3mc-workingmemory",
      "args": []
    }
  }
}

ツール呼び出しの自動承認（Claude Code のみ）

デフォルトでは、Claude Code は MCP ツールを呼び出すたびにユーザーに確認します。接続された AI が「許可しますか？」という確認で止まらない、完全自動のメモリループを実現するには、Claude Code の設定で n3mc-workingmemory ツールを permissions.allow に追加する必要があります。

プラグインをインストールすると、この設定は自動的に行われます — /plugin install n3mc-workingmemory@neuralnexusnote でインストールすると、SessionStart フックが hooks/install_permissions.py を実行し、~/.claude/settings.json に6つの mcp__n3mc-workingmemory__* ツールを冪等に追加します。手動で編集する必要はありません。このフックは不足している項目が1つ以上ある場合にのみ書き込み、無関係なフィールドには一切触れません。hooks.json のコマンドは、python → py（Windows Python Launcher）→ python3 の順に || でフォールバックするため、これらのいずれかが PATH にあればフックは動作します。3つすべてが見つからない場合にのみ、Claude Code の /plugins の Errors タブに表示されるよう、ゼロ以外の終了コードを返します。これにより、気づかれないまま失敗することを防ぎます。

同じフックは uvx の事前チェック も実行します — プラグインマニフェストは uvx --from n3memorycore-mcp-lite n3mc-workingmemory を使って MCP サーバーを起動するため、uvx が見つからない場合、MCP ランチャーでは原因が分かりにくい ENOENT として表示されます。フックは shutil.which("uvx") を呼び出し、見つからない場合は、実行可能な対処方法を示すインストール案内（pipx install uv、curl -LsSf https://astral.sh/uv/install.sh | sh、およびドキュメントの URL）を英日併記で標準エラー出力に書き込みます。これにより、ユーザーは /plugins の Errors タブで具体的な案内を確認できます。権限のインストール自体は成功しているため、フックは引き続き終了コード 0 を返します。

プラグインを使わずにインストールした場合（例：claude mcp add や手動での .mcp.json の設定）、または利用可能な Python インタープリターがない場合は、以下のブロックを ~/.claude/settings.json（ユーザー共通。推奨）または .claude/settings.json（プロジェクトごと）に手動で追加してください。

{
  "permissions": {
    "allow": [
      "mcp__n3mc-workingmemory__search_memory",
      "mcp__n3mc-workingmemory__save_memory",
      "mcp__n3mc-workingmemory__list_memories",
      "mcp__n3mc-workingmemory__delete_memory",
      "mcp__n3mc-workingmemory__delete_memories_by_session",
      "mcp__n3mc-workingmemory__repair_memory"
    ]
  }
}

これを設定しないと、save_memory / search_memory を呼び出すたびに承認を求められ、ユーザーが席を外している場合、AI は処理を続行できません。Claude Desktop にはツールごとの権限ゲートがないため、この設定は不要です。

データの保存場所

Lite ビルドはデータベースをディスクに保存しません — メモリは Redis に保存され、自動的に有効期限が切れます。プラットフォーム標準のユーザーデータディレクトリには、小さな config.json だけが置かれます。

OS	パス
Windows	%LOCALAPPDATA%\n3mc-workingmemory\
macOS	~/Library/Application Support/n3mc-workingmemory/
Linux	~/.local/share/n3mc-workingmemory/

N3MC_DATA_DIR 環境変数で変更できます。

設定

初回実行時に、owner_id と local_id にランダムな UUID を設定した config.json が自動生成されます。編集可能なデフォルト値は次のとおりです。

{
  "owner_id":                 "<uuid>",
  "local_id":                 "<uuid>",
  "redis_url":                "redis://localhost:6379/0",
  "ttl_seconds":              604800,
  "dedup_threshold":          0.95,
  "half_life_days":           3,
  "bm25_min_threshold":       0.1,
  "search_result_limit":      20,
  "context_char_limit":       3000,
  "min_score":                0.2,
  "search_query_max_chars":   2000,
  "chunk_threshold":          400,
  "chunk_overlap":            100,
  "access_count_enabled":     true,
  "access_count_weight":      0.02,
  "access_count_max_boost":   0.5,
  "ttl_refresh_on_search":    true,
  "ttl_refresh_top_k":        5,
  "lexical_rerank_enabled":   true,
  "rerank_weight":            0.3,
  "rerank_phrase_weight":     0.2,
  "b_session_match":          1.0,
  "b_session_mismatch":       0.6,
  "skip_code_blocks":         false
}

• redis_url — 接続 URL です。N3MC_REDIS_URL 環境変数が優先されます。
• ttl_seconds — 新しいメモリーと sha-guard に適用される TTL です（デフォルトは 7 日）。
• chunk_threshold / chunk_overlap — スライディングウィンドウのサイズとオーバーラップ（文字数）です。本文がしきい値を超えると、逐語的な再呼び出しのために親ドキュメント＋チャンクの経路が使われます。
• access_count_* — アクセス頻度に基づく自動重要度設定です。検索結果の上位 K 件には、今後のクエリで上限付きのブーストが適用されます。
• ttl_refresh_on_search / ttl_refresh_top_k — 検索のたびに上位 K 件の TTL をリセットします（リセットのみで、新規保存時の TTL より延長されることはありません）。
• lexical_rerank_* / rerank_weight / rerank_phrase_weight — 軽量な融合後の語彙再ランキング機能です（CPU のみ）。
• b_session_match / b_session_mismatch — 保存された session_id が一致する行と、別のプロジェクトの行に対する乗算型のランキングブーストです（デフォルトはそれぞれ 1.0 と 0.6）。同じ Redis インスタンス内で、無関係なプロジェクトの行よりも特定のプロジェクトのメモリーを優先して表示するには、save_memory と search_memory に同じ session_id を渡してください。このバイアスを無効にするには、両方を 1.0 に設定します。
• skip_code_blocks — true の場合、save_memory はトリプルバッククォートのフェンス（```）を含むペイロードを拒否し、status: "skipped_code" を返します。デフォルトは false です。FastAPI 時代の N3MemoryCore のようにコードを除外する場合（コードをメモリーインデックスに一切含めない場合。コードの Git/IDE 履歴がワークフローにすでにあり、Redis には文章による判断や計画だけを保存したい場合に便利です）は、true に設定してください。

すべてのフィールドの詳細については、仕様の §6 を参照してください。

多言語サポート

組み込みで、CPU のみで動作し、LLM も GPU も必要ありません。同じ単語をどのように入力しても、検索と重複排除は同じように動作します。

レイヤー	動作	実際の例
NFKC 正規化	SHA / 埋め込み / BM25 の前に互換文字を統一します	ｱﾙﾌｧ ↔ アルファ、１２３ ↔ 123、fi ↔ fi
バイグラム BM25 サイドチャネル	空白を使わない文字体系向けに、重複するバイグラムを生成します	記憶装置 → 記憶 憶装 装置。韓国語（안녕하세요）、タイ語（สวัสดี）、ラオ語、ミャンマー語、クメール語も同様です
発音区別符号の統一	ラテン文字、ギリシャ文字、キリル文字の単語も、結合文字を除いた形でインデックス化します	café は cafe に、Ångström は Angstrom に一致します
multilingual-e5-base 埋め込み	100 以上の言語を横断する多言語の意味空間です	言語をまたいだ言い換えの検索

これらはすべて、save_memory と search_memory の呼び出しごとに自動で実行されます。 生の content フィールドが書き換えられることはありません。逐語的な再呼び出し（仕様の §3.11）では、元のバイト列がバイト単位でそのまま返されます。

エンコーディングの安全性

ツール本体の実行前に、2 層の防御処理が実行されます（仕様の §3.13）。 Free ビルドと同じガードを、一対一で移植しています。

1. stdio の UTF-8 再設定 — モジュールのインポート時に、sys.stdin / sys.stdout / sys.stderr が encoding="utf-8" に切り替えられます。Windows の日本語環境では、デフォルトのコンソールコードページが cp932 であるため、そのままでは MCP JSON-RPC チャネル上のすべての非 ASCII バイトが文字化けします。POSIX システムはすでに UTF-8 のため、この呼び出しは安全なノーオペレーションです。
2. 孤立サロゲートのサニタイズ — すべての save_memory.content と search_memory.query は、.encode("utf-8") を呼び出す前に sanitize_surrogates() を通されます。孤立した UTF-16 サロゲートの半分（U+D800–U+DFFF）は、Windows のサブプロセスパイプから渡された UTF-8 バイト列を、Python デコーダーが errors="surrogateescape" を使ってデコードした場合に発生します。これらは json.loads では元に戻せますが、SHA1 / Redis HSET / 埋め込みの処理時に UnicodeEncodeError を引き起こします。このガードがなければ、書き込み全体が気づかれないまま失われます。この関数は再帰的に処理するため、内部にサロゲートを含む JSON ペイロードも一度の処理でクリーニングされます。

保存ペイロードがすべてサロゲートで構成されている場合、サニタイズ後に空文字列になり、通常の空コンテンツ拒否処理が適用されます — {"status":"error","saved":false,"reason":"empty content"}。

ランキングの計算式

final_score = (0.7 * cosine_similarity + 0.3 * keyword_relevance) * time_decay * b_local * b_session

time_decay   = 2 ^ (-days_elapsed / half_life_days)       (default half-life: 3 days)
b_local      = clamp(0.5, 2.0, stored_importance + access_boost)
access_boost = min(0.5, access_count * 0.02)
b_session    = b_session_match (default 1.0)   if row.session_id == effective_session
             = b_session_mismatch (default 0.6) otherwise

デフォルトの半減期は3日（7日のTTLより短い）です。Liteビルドでは、time_decay に意味があります。新しいメモリのスコアは1.0、3日前のメモリはちょうど0.5、期限切れ間近の7日前のエントリは約0.20となり、最近のコンテキストがランキング上位に表示されます。

自動重要度（アクセス頻度によるブースト）：search_memory がメモリを上位5件の結果として返すたびに、そのメモリの access_count が1増加し、以降のクエリでは b_local が0.02上昇します（上限は+0.5）。LLMによる判断は不要です。CPUのみの自己調整によって、頻繁に役立つメモリが自然に上位に表示されます。

開発

# Start Redis Stack first (see Prerequisites), then:
pip install -e ".[dev]"
pytest tests/ -q

テストではRedisのデータベースインデックス 0（N3MC_REDIS_TEST_URL で設定可能）を対象とし、各テストの前後に FLUSHDB を実行します。RediSearchではDB 0以外にインデックスを作成できないため（Cannot create index on db != 0）、テスト用に別のDBを使うことはできません。テストスイートは、必ずデータを保持していない専用のRedisコンテナに対して実行してください。Redisに接続できない場合、テストは実行されません。

Liteビルドの拡張

動作を変更する場合（ランキングの計算式の変更、クロスエンコーダーリランカーの導入、日本語形態素トークナイザーの組み込みなど）は、このリポジトリに含まれる設計仕様書を参照してください。

• N3MemoryCore_MCP_Spec_EN.md — 設計文書の全文（英語）
• N3MemoryCore_MCP_Spec_JP.md — 日本語版

仕様書の付録Aでは、オプションの拡張機能（クロスエンコーダーリランカー、保存時のチャンク分割、HyDE、日本語形態素解析）について、差し込み箇所とライブラリ候補を示しています。TTL、重複排除、RediSearchの契約を損なわずにコードを編集する際の参考にしてください。

N3MemoryCoreを選ぶ理由（組み込みメモリとの比較）

N3MemoryCoreの自動保存の信頼性は、最新のLLM製品に組み込まれたメモリ機能（例：Claudeの組み込みメモリ）より優れているわけではありません。どちらもLLMが自発的に保存ツールを呼び出すことに依存しており、以下の遵守についてで述べる非決定性も共通しています。違いは別の点にあります。

項目	組み込みメモリ	N3MemoryCore（Lite）
データの所有権	ベンダーがホスト	ご自身のマシン上にあるRedis Stack
クライアントの利用範囲	ベンダーの製品のみ	MCP準拠のあらゆるクライアント（Claude Code、Cursor、Cline、Goose、ご自身のアプリ）
複数AIの連携	1つのAIのメモリ	session_id により、複数のエージェントが同じメモリ名前空間を共有できます。完了したタスクは delete_memories_by_session で整理できます
原文の再現	不透明（要約される場合があります）	親ドキュメント契約 — 全文をバイト単位で正確に返します
検索の内部処理	ブラックボックス	ハイブリッドBM25＋e5ベクトル＋CJKバイグラム＋時間減衰＋軽量リランカー。すべてのパラメーターを確認・調整できます
確認／制御	UIのみ	list_memories／delete_memory／delete_memories_by_session で生のレコードを操作できます
永続性	ベンダーのサービス提供期間に依存	7日間のTTLを持つインメモリRedis — 短期間の利用を想定した設計ですが、コンテナはご自身で管理できます。長期保存には、任意の永続メモリバックエンドを組み合わせてください
調整可能性	固定	half_life_days、chunk_threshold、dedup_threshold、リランカーの重みなど、すべて編集可能です

したがって、N3MemoryCore Liteを実行する価値は、「より信頼性の高い自動保存」ではありません。複数のAIが共有の session_id のもとで連携でき、検索動作を編集でき、原文の再現が契約上保証された、透明性の高い複数クライアント対応の作業メモリレイヤーを自分で所有できることです。（ユーザーが作成した成果物を長期的かつ永続的に保存する場合は、任意の永続メモリバックエンドを組み合わせてください。）

これらの特性がワークフローで重要なら、Liteを使う価値があります。1つのベンダーの製品内で「LLMがセッションをまたいで何かを記憶する」ことだけが必要なら、組み込みメモリのほうがシンプルです。

コンプライアンスについて — MCP は促すことはできますが、強制はできません

このサーバーは、LLM にツールを呼び出させることはできません。MCP プロトコルがサーバーに与える、呼びかけの手段は次の 3 つだけです。

1. tools/list に含まれる ツールの説明 — 毎回のターンで LLM に表示されます。
2. セッション開始時に送信される instructions フィールド — 通常、システムレベルのヒントとして LLM に提示されます。
3. ツールの応答テキスト — ツールを呼び出した際に LLM が読みます。

これら 3 つをすべて活用しています。ツールの説明は明確に記述し、instructions でルールを示し、search_memory / save_memory の応答の末尾には短いリマインダーを付けて、ターンの途中でも自動保存の習慣を再確認できるようにしています。それでも、LLM が実際に従うかどうかは非決定的です。遵守するかどうかは、モデルのツール呼び出しの傾向、MCP クライアントのプロンプト構成（一部のクライアントは instructions フィールドを要約したり削除したりします）、ユーザープロンプトや CLAUDE.md などからの競合する指示に左右されます。

実際には、ほとんどのターンで自動保存は正しく行われますが、そうならないこともあります。特に、短い回答、事実の訂正を行うターン、LLM がユーザーの質問に強く集中しているターンでは起こりやすくなります。保存してほしかった事実が次のセッションで見つからない場合は、「save this」と伝えてください。サーバーは引き続き保存を受け付けられます。

確実に保存したい場合

MCP の仕組みの範囲内では、次の 3 つの方法でこの非決定性を回避できます。

方法 1 — プロンプトで LLM に明示的に依頼する（実用的な回避策、すぐに使えます）。プロンプトに 「save this to N3MemoryCore」 または 「record this in memory」 と書きます。LLM はユーザーからの明示的な依頼には、ほとんどの場合従います。メリット：インフラが不要で、今すぐ使え、あらゆる MCP クライアントで動作します。デメリット：認知的な負担がかかります。忘れずに伝える必要があり、自動ではありません。

フックベースの全トランスクリプト保存

パス 2 — 全トランスクリプトを保存する Claude Code フック（Claude Code のみ、確実に実行されます）。Claude Code はハーネスレベルのフック（Stop など）を公開しており、ハーネスが確実に実行するため、LLM が何かを覚えている必要はありません。Claude Code へのプロンプト 1 つで設定できます。

「各ターンの後に、Claude Code の全トランスクリプトを Lite に自動保存してください。」

Claude Code は次の設定を行います。

• フック入力から transcript_path を読み取り、n3mc_mcp.database.Database を直接インポートし、Lite DB に対して save_memory を呼び出すスクリプト ~/.claude/hooks/save_transcript.py。
• 各アシスタントターンの後にスクリプトを実行する ~/.claude/settings.json 内の hooks.Stop ブロック。async: true を設定し、モデルの読み込みで UI がブロックされないようにします。

動作に関する補足：

• Claude が誤って保存をスキップすることはありません。LLM の動作にかかわらず、ハーネスがフックを実行します。
• MCP の往復によるオーバーヘッドはありません。フックは Redis と直接通信します。
• セッションが長くなると、各ターンのトランスクリプトは近似重複検出（dedup_threshold）によって重複と判定されるため、DB はターンごとに 1 件ではなく、セッションあたり 1 件に近い状態を保ちます。
• 約 200 文字未満のトランスクリプトは、ノイズとしてスキップされます。
• 利点：確実に実行される／モデルの動作に依存しない／保存し忘れる心配がない。
• 欠点：Claude Code のみ（Cursor／Windsurf では別の方法が必要）／フックのプロセスは各ターンで埋め込みモデルを読み込みます（非同期のため UI はブロックされませんが、CPU／I/O のコストがかかります）／Lite の 7 日間 TTL は引き続き適用されるため、この方法で保存したトランスクリプトも 1 週間以内に期限切れになります。長期保存が必要な場合は、同じフックの保存先を永続的なメモリバックエンドに変更してください。

パス 3 — MCP を介さず、Anthropic のファーストパーティ Messages API を直接呼び出す（アーキテクチャの変更）。MCP クライアント（Claude Code など）を介さず、独自のアプリケーションコードから messages.create の tool_use を直接実行します。そうすれば、LLM が何を「判断」したかにかかわらず、毎ターン確実に save_memory を呼び出せます。利点：確実に実行される／あらゆるモデルとクライアントで動作する。欠点：オーケストレーションアプリケーションを自分で作成する必要があります。

「MCP と LLM に任せる」手軽さと、「すべてのターンを保存する」保証は、トレードオフの両極にあります。このサーバーでは、プロトコルで可能な限り強く保存を促す仕組みを備えています。これ以上の保証が必要な場合は、ユーザーまたはクライアント実装者の判断に委ねられます（Claude Code をお使いなら、パス 2 が圧倒的に低コストな選択肢です）。

フォークとコントリビューション

このリポジトリは公開されており、Apache-2.0 ライセンスのもとで提供されています。自由にフォーク、変更、実行できます。フォークして実行する手順は次のとおりです。

git clone https://github.com/<YOU>/n3mcmcp-lite
cd n3mcmcp-lite
docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest tests/ -q                                      # 105 tests, ~30s warm

CI はプッシュと PR のたびに同じマトリクスを実行します。詳細は .github/workflows/test.yml を参照してください。 コーディング規約、仕様を契約として扱う方針、PR チェックリストを含む開発者向けガイド（EN + JP）については、 CONTRIBUTING.md をお読みください。

Claude Code からフォークを実際に使用する場合、上記の pip install -e ".[dev]" に加えて、特別な設定は必要ありません。

1. n3mc-workingmemory コマンドが PATH に追加されています（which n3mc-workingmemory を実行して確認してください）。
2. リポジトリの .mcp.json ではすでにサーバーが宣言されているため、cd n3mcmcp-lite && claude を実行すると、CLI が自動接続します。
3. ほかのクライアント環境（Claude Desktop、別プロジェクトの .mcp.json、ツールの自動承認）については、クイックスタートのステップ 3 の表に具体的な操作が記載されています。

新しいパッケージ名でフォークを公開する場合は、PyPI に再アップロードする前に pyproject.toml の name、[project.urls]、コンソールスクリプト名も編集してください。

トラブルシューティング

Windows：pip install --upgrade が WinError 32（ファイル使用中）で失敗する

症状：

ERROR: Could not install packages due to an OSError: [WinError 32]
The process cannot access the file because it is being used by another process:
'...\Scripts\n3mc-workingmemory.exe' -> '...\Scripts\n3mc-workingmemory.exe.deleteme'

原因：MCP クライアント（Claude Code／Claude Desktop）が子プロセスとして n3mc-workingmemory.exe を現在開いているため、pip が バイナリを置き換えられません。

解決方法 — いずれかを選んでください：

1. 先に MCP クライアントを完全に終了します。 Windows ではウィンドウを閉じるだけでは不十分です。 タスク マネージャーを開き、コマンドラインに n3mc-workingmemory を含むすべての claude／ n3mc-workingmemory.exe／python.exe プロセスを終了してから、 pip install --upgrade を再実行します。
2. グローバルインストールの代わりに uvx を使います — uvx --from n3memorycore-mcp-lite n3mc-workingmemory はセッションごとに分離された 一時的な環境で実行されるため、ロックされるシステムレベルの .exe がありません。

これは Windows のファイルロックに関する特有の問題であり、パッケージの不具合ではありません — wheel 自体は新しい venv に問題なくインストールされます（python -m venv .venv && .venv/Scripts/pip install n3memorycore-mcp-lite）。

pip install 中の ~3memorycore-mcp-lite 警告

次のような行が表示された場合：

WARNING: Ignoring invalid distribution ~3memorycore-mcp-lite

pip が、以前のインストールが書き込みの途中で中断されたことを警告しています （通常は上記のファイルロックの問題が原因です）。残ったディレクトリの名前には先頭に ~ が付いており、害はありませんが警告が表示されます。手動で削除してください：

# Windows
rmdir /s "%LOCALAPPDATA%\Programs\Python\Python312\Lib\site-packages\~3memorycore_mcp_lite-1.5.0.dist-info"

（Python のインストール先に合わせてパスを調整してください。）

ライセンス

Apache License 2.0 — LICENSE を参照してください。

---

_{MCP Registry：mcp-name: io.github.NeuralNexusNote/n3mc-workingmemory}