claude-mem入門 — Claude Codeへ永続メモリを足す仕組み

Posted at 2026-10-31

はじめに

Claude Code のセッションを終えるたびに、直前まで積み上げた文脈が消える。次のセッションで同じ説明をもう一度書く手間に覚えがある人は多いはずだ。この「セッションをまたぐ記憶」を OSS で解決しようとしているのが claude-mem で、npm の週間ダウンロードは 1.5 万件を超える。ただし多くのエージェント連携ツールと同様、便利さの裏でどんな設定がデフォルトで有効になっているかは、実際に触ってみないと分からない。

この記事では、claude-mem を実際にインストール前の状態から動かし、CLI が何をするのかを一つずつ確認する。

この記事で分かること

claude-mem が解決する課題と基本構成
インストール前の状態で CLI が実際にどう振る舞うか
導入前に確認しておきたい設定項目

対象読者

Claude Code をはじめ複数の AI コーディングエージェントを併用している人
OSS のメモリ・コンテキスト管理プラグインの導入を検討している人

検証環境

Node.js: v22.22.2
Bun: 1.3.11
実行日: 2026-07-19（JST）
対象パッケージ: claude-mem v13.11.0（npm dist-tag latest）

TL;DR

claude-mem は --ide オプションだけで claude-code・cursor・opencode・openclaw・windsurf・codex-cli・copilot-cli・antigravity・goose・roo-code・warp の 11 識別子に対応する、セッション間の作業記憶を永続化する Apache-2.0 の OSS。README は Gemini や Hermes との連携も謳うが、--ide 識別子には含まれず対応状況も一様ではない（詳細は本文）。
npx claude-mem install を実行する前でも、status や telemetry status などのサブコマンドは動く。telemetry はデフォルトで有効（オプトアウト方式）だった。
npm view で取得できる公開バージョンは 189（最古 v2.0.2〜最新 v13.11.0）。npm の time メタデータには 2025-08-30 の v2.0.0 の記録も残るが、これは現在は取得できない（unpublish 済みとみられる）。

claude-mem とは何か

claude-mem は「Persistent Context Across Sessions for Every Agent」を掲げる OSS で、GitHub 上のスター数は 87,780（2026-07-19 時点の実測、GitHub 公開 API より)¹。公式リポジトリの説明によると、エージェントがセッション中に行ったツール呼び出しの観察結果を捕捉し、AI で要約・圧縮したうえで、次回以降のセッションに関連情報だけを注入する仕組みだという²。ライセンスは Apache License 2.0 で、README では「permissive でなければ MCP サーバーやロボティクス基盤など幅広い開発ツールに組み込みにくい」という採用理由が示されている。

リポジトリの説明文には「Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More」ともある。ただしこの一文はマーケティング的な要約で、実際に --ide オプションへ渡せる識別子と一致するとは限らない。

CLI コマンド一覧を実機で確認する

npx claude-mem install を実行する前に、隔離したディレクトリで --help を叩いてみた。

$ node --version
v22.22.2
$ npx --yes claude-mem@13.11.0 --help

出力の抜粋:

claude-mem v13.11.0 — persistent memory for AI coding assistants

Install Commands (no Bun required):
  npx claude-mem                     Interactive install
  npx claude-mem install              Interactive install
  npx claude-mem install --ide <id>   Install for specific IDE
  npx claude-mem install --provider claude|gemini|openrouter
  npx claude-mem install --runtime worker|server
  npx claude-mem repair
  npx claude-mem update
  npx claude-mem uninstall

Runtime Commands (requires Bun, delegates to installed plugin):
  npx claude-mem start / stop / restart / status
  npx claude-mem doctor
  npx claude-mem telemetry status|enable|disable
  npx claude-mem server start / stop / status
  npx claude-mem search <query>
  npx claude-mem adopt [--dry-run] [--branch <name>]

IDE Identifiers:
  claude-code, cursor, opencode, openclaw,
  windsurf, codex-cli, copilot-cli, antigravity, goose,
  roo-code, warp

--ide に渡せる識別子は 11 個で、Codex は codex-cli として含まれている。一方で README が名指しした Gemini・Hermes はこの一覧に存在しない。install --provider claude|gemini|openrouter の行にある「gemini」は要約に使う LLM プロバイダの選択肢であり、対応 IDE を示すものではない。Hermes については GitHub 上に「Add native Hermes Agent integration」という Issue が open のまま残っており³、現状は MCP 経由の手動ブリッジでしか繋げないとされている。README の一文だけを見て「Gemini・Hermes もそのまま使える」と判断すると、実際の対応状況とはズレる。

--runtime server を選ぶと Docker で PostgreSQL と Redis を起動し API キーを発行する構成も選べるらしく、個人開発のセッション記憶ツールにしては構成の幅が広い。

インストール前の状態を確認する

install を実行せず、status と telemetry status だけを叩いてみた。プロジェクトの .claude/ 設定に手を入れたくなかったため、セッション用のスクラッチディレクトリで検証している。

$ npx --yes claude-mem@13.11.0 status
claude-mem is not installed.
Run: npx claude-mem install

$ npx --yes claude-mem@13.11.0 telemetry status
Telemetry: ENABLED
Decided by: default (on — no opt-out recorded)
Install ID: none (no telemetry config has been written)
Config file: /root/.claude-mem/telemetry.json

status は未インストールを検知して次のコマンドを案内してくれる、素直な作りだった。一方で telemetry status は install を一度も実行していない状態でも ENABLED を返す。設定ファイル自体はまだ書き出されておらず(no telemetry config has been written)、値はコード側のデフォルトから来ている。つまり claude-mem は「テレメトリを送るかどうか」を最初にユーザーへ聞くのではなく、送る前提で動き、オプトアウトしたい場合は telemetry disable を能動的に叩く設計になっている。

アーキテクチャの中身（公式ドキュメントによる二次情報）

ここから先は今回インストールまでは検証していないため、公式 README の記述に基づく二次情報として紹介する。README によると内部は次の要素で構成されている²。

SessionStart・UserPromptSubmit・PostToolUse・Stop・SessionEnd の 5 種類のライフサイクルフックで、エージェントの行動をイベント単位で捕捉する
ローカルで動く HTTP のワーカーサービス（Bun 管理）が要約・保存処理を担う
セッション・観察・サマリーは SQLite に保存し、意味検索には Chroma ベクトル DB を併用するハイブリッド構成
search / timeline / get_observations の MCP ツールで段階的に情報を取得し、全文を毎回読み込まないことでトークン消費を抑える

この構成が成り立つには Node.js 20.12 以上・Bun・Python パッケージマネージャの uv が必要だとされている²。今回の検証環境（Node v22.22.2・Bun 1.3.11）はどちらも要件を満たしていたが、Bun や uv を常用しない開発環境では追加インストールが発生する点は踏まえておきたい。

導入前に確認しておきたい 3 点

CLI の挙動と README の記述を突き合わせると、導入前に確認すべき点が 3 つ見えてくる。

telemetry は既定で ON: 前章の実機確認どおり、オプトインではなくオプトアウト方式。社内ポリシーでテレメトリ送信を制限しているチームは install 直後に telemetry disable を実行する運用を決めておいたほうがよい。
依存ランタイムが 3 種類: Bun・uv・（--runtime server を選ぶ場合は）Docker が必要になる。CI やサンドボックス環境では事前にインストール可否を確認する必要がある。
adopt はブランチ運用に影響する: npx claude-mem adopt は merge 済みの worktree を親プロジェクトに記録するコマンドで、Git ワークフローに絡む機能があることを示している。Git 操作を伴うツールを導入するときは、既存のブランチ運用ルールと衝突しないか事前に確認したい。

著者視点の発見ポイント

実際に触って意外だったのは、install を一度も実行していない状態でも telemetry status がコード側のデフォルト値をそのまま返してくる点だった。多くの CLI ツールは「未設定」を unknown や not configured として区別して返すが、claude-mem は「未設定 = 有効」という既定値をそのまま表示する。設定ファイルが書き出されていない段階でもこの挙動になるため、status コマンドで「未インストール」と表示されたことをもって「何も送信されない」と早合点しないほうがよい。

もう一つは npm registry から取得した公開履歴だ。npm view claude-mem versions --json で取得できる公開バージョンは 189（最古 v2.0.2、最新 v13.11.0）。npm view claude-mem time --json のメタデータには 2025-08-30 付けで v2.0.0 の記録も残るが、versions の一覧には含まれておらず、公開後に unpublish された可能性が高い。189 バージョンを 2025-08-30〜2026-07-13 の約 10.5 か月で割ると月あたり 18 リリース前後というペースで、メジャーバージョンだけでも 2 から 13 まで駆け上がっている。開発が活発な証拠ではあるが、破壊的変更を伴うメジャーアップデートが月に 1 回以上のペースで起きうるという意味でもあり、本番運用に組み込む場合はバージョン固定と更新方針を先に決めておくほうが安全そうだ。

まとめ

claude-mem の --ide オプションには 11 個の識別子が並んでいたが、README が名指しする Gemini・Hermes はその中には無かった。「対応エージェントの多さ」を謳う説明文と、実際に CLI が受け付ける識別子には差があり、README の一文だけで導入対象を判断するのは避けたほうがよい。加えて、インストール前の CLI 挙動を確認しただけでも「telemetry は既定で有効」「依存ランタイムが 3 種類」というチェックすべき点が見つかった。セッションをまたぐ記憶を諦めていた人は、まず telemetry status と --help だけを叩いて、自分の環境の --ide 識別子とポリシーに合うかを確認してから install に進むとよさそうだ。

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up