Mnemoverse MCP memoryをClaude Codeにつなぐ — 永続メモリの手順

Mnemoverse MCP memoryとは — 会話をまたぐ記憶をアカウント側に持つ仕組み

Mnemoverseは、MCP対応のAIツールに長期記憶を足すサービスです。記憶はMnemoverseのアカウントに置かれ、@mnemoverse/mcp-memory-server というnpmパッケージ(MITライセンス)がClaude Codeなどとの橋渡しをします。

つなぎ方は2通りあります。

どちらの経路でも記憶の置き場所は同じです。0.9.0以降は、2つの経路が同じ11個のツールを出します。経路を乗り換えても、同じアカウントなら記憶は引き継がれます。

この記事の主題はClaude Codeへの導入です。Claude Desktopの設定も後半に載せます。外部の記憶サービスという意味ではClaudeとMem0の連携が近い話ですが、Mem0とは別の製品です。Claude自身のメモリ機能との違いはClaudeのメモリとChatGPTのメモリの違いにあります。

先に選ぶ — OAuthとAPIキーのどちらにするか

迷ったら、まずOAuthを選びます。キーを貼る手間がなく、インストールもありません。

APIキー方式を選ぶ理由は、主に2つです。ブラウザーのない環境で動かすとき。そして、無人で動くエージェントやCIに使うときです。

OAuthのコネクタは、ホストアプリのサインインに紐づきます。アカウントを切り替えたり、アプリが再認証したりすると、コネクタが外れることがあります。外れてもエラーは出ず、メモリのツールが静かに消えます。ローカルのパッケージはキーを設定ファイルから読むだけなので、サインアウトやアカウント切り替えの影響を受けません。

Claude CodeにOAuthでつなぐ手順

コマンドは1行です。--scope user を付けると、すべてのプロジェクトで使えます。

claude mcp add --scope user --transport http mnemoverse \
  https://mcp.mnemoverse.com/mcp

追加しただけでは、ブラウザーは開きません。サインインは別の操作です。

--scope user を省くと、コマンドを実行したディレクトリだけに追加されます。Claude Code側の仕様で、スコープを省くと local になるためです。

claude.aiでコネクタを足している場合は、Claude Code側の作業を減らせます。claude.aiアカウントでClaude Codeにログインしていると、claude.aiで追加したMCPサーバーが自動で使えます。claude.aiのカスタムコネクタにURL https://mcp.mnemoverse.com/mcp を入れれば足ります。無料プランのカスタムコネクタは1つまでです。

Claude CodeにAPIキーでつなぐ手順(ローカルのnpxサーバー)

APIキーは、console.mnemoverse.comで発行します。無料枠はクレジットカード不要です。キーは mk_live_ で始まります。

claude mcp add mnemoverse --scope user \
  -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY \
  -e MNEMOVERSE_API_URL=https://core.mnemoverse.com/api/v1 \
  -- npx -y @mnemoverse/mcp-memory-server@latest

mk_live_YOUR_KEY は自分のキーに置き換えます。プレースホルダーのまま登録しても、サーバーは起動します。そのかわり、すべてのメモリ呼び出しが失敗します。

-- は省けません。-- の左側がClaude Code自身のオプションで、右側がサーバーを起動するコマンドです。Claude Codeの仕様では、-- より後ろはそのままサーバーに渡されます。

PowerShellでは、\ による改行が通りません。同じコマンドを1行にして貼ります。

MNEMOVERSE_API_URL は、サーバーが話しかけるREST APIの宛先です。MCPのエンドポイントではないので、コネクタのURL欄には貼らないでください。既定値のままでよければ、設定は省略できます。

キーをプロジェクトに残さない

--scope project で追加すると、チームで共有する .mcp.json に書かれます。キーを -e で直接渡したまま project を選ぶと、コミット対象のファイルにキーが残ります。個人のキーを置く先は user か local です。

Claude Desktopに入れる場合

Claude Desktopには2つの道があります。

• リモート: 「Customize」→「Connectors」→「+」→「Add custom connector」を開き、URLに https://mcp.mnemoverse.com/mcp を貼ります。初回の利用時にOAuthの画面が開きます。JSONの編集は要りません。
• ローカル: 設定ファイルに、次のブロックを足して再起動します。

macOSでは ~/Library/Application Support/Claude/claude_desktop_config.json、Windowsでは %APPDATA%\Claude\claude_desktop_config.json です。

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

つないだだけでは、Claudeは記憶を使わない

ここが最もつまずきやすい点です。ツールを足しても、使うかどうかはモデルが毎回判断します。何も指示がなければ、Claudeは手元の文脈で答えてしまい、Mnemoverseは呼ばれません。ツールの説明は「何をするか」を書いていて、「頼まれなくても使え」とは書いていません。

対策は、記憶のルールを常設の指示に書くことです。Claude Codeなら、プロジェクト直下の CLAUDE.md、または全プロジェクト共通の ~/.claude/CLAUDE.md です。サーバーが持つ setup_memory というプロンプトが、ルールの全文を出します。

/mcp__mnemoverse__setup_memory claude-code

コマンド名の mnemoverse の部分は、claude mcp add で付けたサーバー名です。別の名前で登録したなら、/ を打って(MCP)と付いた候補から選びます。

出てくるルールは、次の5行です。

## Memory (Mnemoverse)
 
- Before answering something that may depend on an earlier session (my preferences, past decisions, project setup, people), search memory with memory_read.
- When I state a lasting preference or make a decision, or you learn a durable fact about this project, save it with memory_write as one self-contained statement. You do not need to ask me first.
- When a message also carries a durable fact (who now owns or does what, a lesson learned, a new convention), save that fact with memory_write before doing the rest of the task.
- After acting on recalled memories, rate them with memory_feedback: helpful or not. For a shared room's memories, pass the room's address as domain; a read-only member cannot rate them.
- Never store passwords, API keys, payment data, MFA codes, government IDs, or health records.

最後の1行は、保存してはいけないものを決める行です。パスワード、APIキー、決済情報、MFAコード、公的な身分証の番号、健康記録が対象です。

ルールを書いたファイルはコミットしておくと、チームの全員のエージェントが同じ癖を持ちます。Claude.aiやClaude Desktopには CLAUDE.md がありません。「Settings」の「Instructions for Claude」か、プロジェクトの指示欄に貼ります。こちらはアカウントごとの設定なので、メンバーが各自で入れます。

プロジェクトごとに記憶を分ける

上のルールには、保存先のdomain(名前空間)の指定がありません。何も指定せずに保存すると、すべて既定の general に入ります。読み出しでdomainを省くと、自分の全domainが対象です。複数のリポジトリで同じアカウントを使うと、あるリポジトリの「このプロジェクトはpnpmを使う」が別のリポジトリで返ってきます。

リポジトリごとのdomainを、そのリポジトリの CLAUDE.md に1行足して分けます。~/.claude/CLAUDE.md には書きません。全プロジェクトに効いてしまうからです。

- This repository's memory domain is "project:acme-api". Pass domain "project:acme-api" to memory_write when you save a fact about this project, and to memory_read and memory_list_recent when you look one up. Save preferences that hold in every project without a domain.

acme-api の部分は自分のリポジトリ名に替えます。名前は大文字小文字や空白まで完全一致で扱われ、project:acme-api と project:Acme-API は別の保管先です。memory_stats が自分のdomain一覧を返すので、エージェントに正確な名前を拾わせられます。

11個のツールと、使い分けで迷う2つ

ツールは用途で4つに分かれます。

vault_list は値を返しません。削除系のツールもありません。0.9.0で2つの削除ツールが外れ、削除はREST APIの管理操作になりました。間違った記憶をエージェント経由で直すなら、訂正した記憶を新しく書きます。

memory_readとmemory_list_recentの違い

記憶が空だと結論してしまう最も多い原因は、この2つの取り違えです。

• memory_read は意味検索です。「Xについて何を知っているか」に答え、クエリに合わない記憶は返しません。
• memory_list_recent は時間をさかのぼります。「最近何があったか」に答え、省略なしで返します。

休み明けの再開や、共有ルームの新着確認には memory_list_recent を使います。1ページは最大100件で、続きがあればカーソルが返ります。両方とも since と until で期間を区切れます。

動かないときの切り分け

症状ごとに原因が違います。上から順に当てはめます。

Failed to connectの直し方

起動に失敗したときの手順です。順番に試します。

1. 少し待ち、claude mcp list をやり直す。
2. 初回のダウンロードが30秒の起動制限を超えるなら、MCP_TIMEOUT=60000 claude のようにミリ秒で延ばして起動する。
3. npx -y @mnemoverse/mcp-memory-server@latest を手で実行する。起動して入力待ちになれば、サーバー自体は正常。
4. claude mcp get mnemoverse の内容と比べる。-- の付け忘れが典型。
5. 同じ名前が既にあると追加は失敗する。claude mcp remove mnemoverse で消して、追加し直す。

Windows PowerShellで「スクリプトの実行が無効」と出るなら、原因はNode.jsではなく npx.ps1 の実行ポリシーです。npx を npx.cmd に替えます。

古いエントリに隠されていないか

Claude Codeは、同じ名前のサーバーを1つのスコープからだけ読みます。優先順はlocal、project、userの順です。

OAuthからAPIキーへ乗り換えた場合も、同じ罠に当たります。

無料枠で足りるか

料金表の数値は次のとおりです。

1日のクエリには、読み、書き、評価がすべて含まれます。成功した要求だけが数えられます。エージェントが毎ターン memory_read を呼ぶ設定にすると、1日1,000回は意外と早く尽きます。上位プランはProが月額29ドルで、1日5万クエリと50万件です。Teamは月額149ドルで、1日50万クエリと500万件です。

記憶を入れる前に決めておきたいこと

何を記憶させるかを先に決めておきます。Mnemoverseが挙げる例は、好み、プロジェクトの前提、学んだ教訓、決定、人、パターンの6種です。

• 好み: 「パッケージマネージャーはpnpm」
• 決定: 「キャッシュ重視でGraphQLでなくRESTを選んだ」
• 教訓: 「金曜にデプロイしない」

1件は1つの事実にします。上のルールも「自己完結した1つの文として保存する」と指示しています。memory_write の本文は1〜1万字です。

別のツールから使う場面を試すなら、ドキュメントの例が簡潔です。Claude Codeで「ステージングのデプロイは make deploy-staging を通すとMnemoverseに記憶して」と頼みます。後日、別のツールで「ここでステージングにデプロイするには?」と聞きます。両方が同じアカウントにつながっていれば、答えが返ります。同一ツールだけの再現は、ツール自身の記憶でも起きるので、検証になりません。

Claude Code自身の自動メモリを調整したい場合は、自動メモリの保存先変更とオフ設定が別の話です。Claude Codeの全体像はClaude Codeとはにまとまっています。

よくある質問

共有ルームを使うと、他の人にも記憶が見えますか

ルームはアカウントをまたぐ共有の記憶です。招待コードで参加したメンバーが、xroom:<room_id> を domain に渡して読み書きします。ルームはBetaです。domain を省いた読み出しはルームを検索しません。0.16.0以降は、検索しなかったルームの宛先が返答の末尾に出ます。