memshelf-mcp

memshelf-mcp

エージェントのメモリを棚に置き、インデックスを渡しましょう。

                              _          _  __
 _ __ ___   ___ _ __ ___  ___| |__   ___| |/ _|
| '_ ` _ \ / _ \ '_ ` _ \/ __| '_ \ / _ \ | |_
| | | | | |  __/ | | | | \__ \ | | |  __/ |  _|
|_| |_| |_|\___|_| |_| |_|___/_| |_|\___|_|_|
  ____________________________________________
 | INDEX >> | E-01 | E-02 | E-03 | E-04 | ... |
 |__________|______|______|______|______|_____|
        memory shelves for AI agents

これは何か

長時間にわたるエージェントのセッションでは、履歴を再送するたびにトークンを消費し、情報が失われる自動圧縮によって詳細も失われます。memshelf は、docshelf のパターン――コンテキストには小さなインデックスを置き、必要に応じて本文を取得する――を、エージェント自身の作業メモリに適用します。

1. 終了した会話のトピック、調査内容のダンプ、大量のツール出力を、Markdown のエピソードとしてローカルの棚に移します。
2. 各エピソードには、LLM が作成し、契約に照らして検証されたダイジェストが付属します。ダイジェストには、決定事項、却下した選択肢、成果物、未解決の話題が保持されます。
3. エージェントは INDEX.md（数キロバイト）とダイジェストだけをコンテキストに保持し、MCP 経由で INDEX → エピソード → セクションの抜粋をたどって、正確なセクションを想起します。

一言で表すと、claude-mem のループ、git の基盤、docshelf のナビゲーション――grep、差分確認、レビューができ、ホスト間で持ち運べるエピソード記憶です。デフォルトではプライベートかつローカルです。標準のストレージモードでは、リモートが設定されていないローカルの git リポジトリを使用します。ツールは公開されていますが、メモリは公開されません。

約束ではなく、実測値

実際の棚で1週間使ってみた結果です。詳しい数値と方法については、docs/demo.md をご覧ください。

指標	結果
棚に保存されたエピソード	34
各セッションで常時必要なコスト（INDEX + ダイジェスト）	約8.6Kトークン
エピソードが置き換える棚上の情報量	約1.9Mトークン — 約220 : 1
メモリから1つの質問に回答するコスト	約1.8Kトークン（INDEX + 1つのエピソード）
想起テスト：新しいエージェント、INDEX のパスのみ	5 / 5 — 見落としゼロ、過剰取得ゼロ

トークン数はすべて文字数÷4で計算しているため、比率は推定方式に左右されません。絶対数はトークナイザーによって変わります。

クイックスタート

MCP サーバーとして使用する場合：

# Claude Code
claude mcp add memshelf -- uvx memshelf-mcp

// Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "memshelf": { "command": "uvx", "args": ["memshelf-mcp"] }
  }
}

Claude Desktop 拡張機能として使用する場合 — adapters/claude-desktop/： Settings → Extensions からインストールする .mcpb バンドルです。Default shelf の設定を利用すれば、呼び出しのたびにパスを指定する必要はありません。Python さえ含め、追加でインストールするものはありません。

Claude Code プラグインとして使用する場合 — adapters/claude-code/： /shelve スキルに加え、SessionStart / SessionEnd / PreCompact フックが含まれます。

または、シェルから使用する場合（pip install memshelf-mcp、Python ≥ 3.10）— MCP を使わずに同じループを実行できます。

memshelf init   --shelf ~/my-shelf --name "My working memory"
memshelf shelve --shelf ~/my-shelf --slug 2026-07-23-topic --kind topic \
  --digest "What was decided, what was rejected and why, what stays open." \
  --section "Decisions=What was decided, and what was rejected instead — one line each."
memshelf recall --shelf ~/my-shelf --id 2026-07-23-topic --section Decisions --log
memshelf rebuild --shelf ~/my-shelf  # render ledger/INDEX from the episode (a bot's job on shelves that have one)
memshelf stats  --shelf ~/my-shelf   # claimed + realized savings
memshelf doctor --shelf ~/my-shelf   # exit 1 on integrity errors

pip install 'memshelf-mcp[semantic]' を実行すると、埋め込みサイドカーが追加され、search で言い換えや他の言語も検索できるようになります（memshelf semantic build --shelf ~/my-shelf を一度実行します。MEMSHELF_SEMANTIC=off で無効にできます）。これはオプションです。基本インストールは grep のみのままで、軽量さも変わりません。

ツール一覧

各ジョブに1つの動詞を割り当てます。MCP（memshelf_*）と CLI で同じ名前を使います （詳細な説明は docs/tools.md を参照してください）。

ツール	機能
init	メモリーシェルフを作成（または補充）します：docshelf レイアウトと固定カテゴリを設定します
shelve	完了したトピックを1つ、永続的でインデックス化されたエピソードとして保存します。--amend はその場で書き換えます
lint_digest	シェルフに触れずに、ダイジェストが契約に準拠しているか検証します
import	エクスポートした会話全体をコンテキストに取り込まずに、遡ってシェルフに保存します
index	シェルフの INDEX（簡潔な想起の入口）を返します
recall	IDでエピソードを取得するか、そのエピソードの単一の ## Section を取得します
search	シェルフを grep し、一致するエピソードを返します
stats	シェルフのトークン収支：常時コストと保存量、見積もりと実績
advise	コンテキストの構成と、削減できる内容を提示します。提案のみです
rebuild	エピソードから、すべての派生ファイルを再生成します
rollup	期間を1つのダイジェスト集約でアーカイブします
purge	retain_until を過ぎたエピソードを削除し、インデックスを再作成します。デフォルトはドライランです
resolve	複数ライター間の競合を解決します。派生データを再生成し、想起ログを統合します
doctor	エピソードのスキーマ、保存時のダイジェスト契約、シークレットの形式、インデックスの肥大化を診断します
freshness	CLI 専用 — どのインストール済みコンシューマー（pipx、Desktop 拡張機能）が呼び出しに応答するか、また何がマージ済みで未リリースかを確認します（#125）
sync	CLI 専用 — シェルフのクローンをリモートから取得し、早送りマージします（#157）
prune-splits	CLI 専用 — git が認識していない H2 分割ディレクトリを削除します（#109 の移行用）
tags	CLI 専用 — frontmatter のタグごとにエピソードをグループ化します（#18）
graph	CLI 専用 — どのエピソードがどのエピソードに言及しているかを、エピソード間の ID 参照として JSON または Mermaid で表示します（#18）
retro	CLI 専用 — シェルフの1四半期分を Markdown の振り返りとして出力します（#18）
fork	CLI 専用 — INDEX と選択したエピソードまたはセクションから新しいセッションを開始します（#18）
mirror	CLI 専用 — INDEX（± エピソード）を、スマートフォンで読める単一の自己完結型 HTML ページにします（#18）
semantic	CLI 専用 — search をハイブリッド検索にする埋め込みサイドカーの build／status／drop を実行します。シェルフの外部に配置され、pip install 'memshelf-mcp[semantic]' が必要です（#17）
search-bench	CLI 専用 — query<TAB>expected-id ファイルを使って、grep とハイブリッド検索の hit@1／hit@k／MRR を計測します（#17）

ツールが適用するルール

ダイジェストは慣例ではなく、契約です。 本文を取得する前の想起で読まれるのはダイジェストだけなので、内容が弱いとエピソード全体の価値が下がります。 lint_digest は副作用なしで、shelve と同じバリデーターを実行します（--strict を指定すると警告も失敗扱いになります）。エラーがあるとシェルフへの保存はブロックされますが、警告ではブロックされません。参照のみのダイジェストに判断を示す記述がなくても問題ありません。不適切なダイジェストを拒否するのは機能の一部です。ツールは修正が必要な箇所を正確に表示し、何も書き込みません。

--amend はパイプライン全体を再実行します — リダクション、ダイジェスト契約、構成をやり直すため、修正後のエピソードも新規エピソードと同じ保護が適用されます。ファイルを手作業で編集した場合はそうなりません。シェルフに存在しないスラッグを修正しようとすると、新規作成ではなくエラーになります。

エピソードがソースであり、それ以外はすべて出力です。 ledger.tsv、INDEX.md、stats.svg と各カテゴリの .meta.json は派生ファイルです。 shelve はエピソードのみを書き込み、コミットします。rebuild は残りを生成します。4つすべてを削除しても、rebuild ですべてがバイト単位で同一に復元されます。これにより、2つのセッションが並行してシェルフに保存しても問題になりません。設計上、マージは競合なく完了します。共有シェルフでは、main 上の派生ファイルをボットに管理させてください — すぐにコピーできるワークフローは adapters/shelf-repo/ にあります。rebuild --adopt は既存のシェルフを一度だけ移行し、rebuild --check は CI のガードとして機能します。

誤るとマージ競合の原因になるため、明確にしておくべき点が2つあります。

• 正しく shelve した直後に、すべてのブランチで、main も含めて、doctor が no-ledger-row と stale-index を報告します。 何も壊れていません。エピソードは書き込まれていますが、派生ファイルはまだ生成されていません。次の rebuild で解消されます。ボットがあるシェルフでは、ボットの実行時に解消されます。
• 警告を消すために、派生ファイルを手作業で再生成してコミットしないでください。 これこそ、分離によって解消される競合の種類です。手作業で再生成した ledger.tsv／INDEX.md／stats.svg とボットの生成物がぶつかり、構造上、マージがクリーンではなくなります。レンダラーが処理するのを待ってください。ボットのないシェルフでは、独立した手順として memshelf rebuild --shelf . を実行してください。

エピソードが届き続けているのに、これらの警告が 1 日 続く場合は、状態が異なります。レンダラーの遅延ではなく、停止しています。doctor はその状態を、エラー重大度の derived-stale として別途報告します。この 1 日は、レンダラーが作業を最初に確認できた時点から数えます。台帳の最終コミット時点からではありません。昨日から台帳に変更がないシェルフに数分前にプッシュされたエピソードは、レンダラーについて何も示しません。そうでないと判断した結果、読者が手動で rebuild を実行することになりました。それこそ、この分離全体で避けようとしている競合です。

その到着時刻は、このクローンの追跡対象 upstream の reflog から読み取ります。ref がここでいつ動いたかを記録する、唯一のローカル記録です。コミット日時は代わりになりません。コミット日時が示すのはエピソードが書かれた時刻です。「今は shelve して、確認後に push する」ことは文書化された作業方法なので、両者の間に稼働日ほどの差が生じることもあります。reflog から読み取れない場合、新しいクローンでは reflog が空から始まります。CI や一時的なエージェントセッションはそのように実行されます。その場合、doctor は判定を決めつけず、unknown レベルの renderer-wait-unknown を報告します。そこでは「停止している」と「1 分前に作業を渡されたばかり」は同じように見えるため、レンダラーは観測可能な場所、つまり専用ジョブの実行結果で判断する必要があります。upstream のないシェルフでは、配慮すべきレンダラーが存在しないため、台帳自体の経過時間を基準にします。

レンダラーの判定基準となる ref は、チェックアウトが追跡している ref ではなく、レンダーブランチです（#180）。ボットがレンダリングするのは 1 つのブランチだけです。リモートのデフォルトブランチを、クローンにあれば origin/HEAD、なければ origin/main、それもなければ origin/master として読み取ります。そのため、PR ブランチにいるクローンは、origin/<pr-branch> にしかないエピソードについて derived-stale と通知されません。そのエピソードはレンダラーではなく、マージを待つ状態です。doctor は警告 upstream-not-rendered でそのことを伝えます。レンダーブランチに届いたエピソードは、PR ブランチからでもそこで判定されます。また、どちらのブランチでもローカルコミットは episode-unpushed のままです。

stale-index をいつまでも残す 3 つ目の原因もありましたが、文書化するのではなく修正しました。docshelf は 50 KiB を超えるエピソードを、隣接するセクションファイルに分割していました。shelve はエピソードだけをコミットしていたため、それ以降、この作業コピーは他のチェックアウトでは生成できない INDEX をレンダリングしていました。どの rebuild でも解消できず、search は 1 台のマシンにしか存在しないアドレスを返していました（#109）。shelve はもう分割しません。このようなディレクトリがすでにあるシェルフでは、memshelf prune-splits --shelf . --apply で削除するまで local-split-dir が報告され続けます。エピソードファイルにはすべてのセクションが含まれているため、失われるものはありません。--apply を指定しなければドライランになり、コミット済みの分割ディレクトリは報告されますが、そのまま残されます。

advise は提案するだけで、書き込みは行いません。 このツールは、プロジェクトの立ち上げのきっかけとなった問い、つまり 使われていないトピックが 30K トークンを 40 分間占有している という問いに答えます。ツールからは作業ウィンドウを見られないため、何が入っているかを伝える必要があります。

memshelf advise --shelf ~/my-shelf \
  --occupant 'auth refactor=42000,closed' \
  --occupant 'search dump=9000,idle=18' \
  --occupant 'Case B verdict=12000,live,episode=2026-07-22-case-b-verdict'

誠実さを保つための要素は 3 つあります。自分自身も数えます（INDEX とダイジェストをレポートに含め、除外しません）。削除を提案する前に episode= の主張を検証します。そして差し引きの値を報告します。自分のダイジェストのコストをまかなえないほど小さなトピックは、提案されません。 ロールアップはナビゲーションだけを縮小し、それ以外は何も変えません。 INDEX がウィンドウの実質的な容量を占めるほど大きくなったら、rollup は一定期間をひとつのダイジェストにまとめたダイジェストへと集約し、元の項目を archive/ に移します。元の項目は引き続き recall と search からアクセスでき、台帳の各行もすべてそのまま残ります。ロールアップのダイジェストを作るのはあなたであり、ツールではありません。四半期をまとめることは、ツールにはできない作業だからです。

index-bloat はロールアップを行う理由ではありません。 INDEX にはエピソードが並ぶため、設計上、棚の項目が増えるほどサイズも大きくなります。予算も棚に合わせて増えます （INDEX_BASE_TOKENS + INDEX_TOKENS_PER_ENTRY × listed）。したがって、予算超過は項目が多すぎることではなく、項目のコストが高すぎることを意味します。つまり、doctor は1行あたりのコストを報告し、解決策はその行を短くして rebuild することです。ロールアップでは項目とその割り当て量が一緒に減るだけで、価格は変わりません。この2つの対応を逆にしていたため、書式の問題を黙らせる標準的な方法が「メモリの3分の1をアーカイブする」ことになっていました。

purge が削除するのは作業ツリーであり、履歴ではありません。 保持期間はエピソードごとにオプトインで設定します（--retain-until）。purge は --apply を指定するまでドライランです。指定したとしても、ファイルは引き続き Git の履歴に残ります。完全に消去するには、リポジトリ全体に対して意図的に filter-repo を実行する必要があります。これはツール呼び出しの副作用として起きることは決してなく、パージレポートにもその旨が記載されます。

resolve は派生パスを再生成しますが、マージはしません — 派生ファイルには履歴がなく、現在の正しい値だけがあるためです。結合する唯一のファイルは recall-log.tsv です。recall はエピソードについての事実ではなく、イベントだからです。競合しているエピソードはコンテンツの問題であり、仕組みの問題ではありません。resolve はそれを報告し、処理を行いません。

ツールの回答では、その背後にあるコードが古くなっている場合にそれを知らせます。 同じコードは5つの方法で提供され、リリース間でバージョン番号は変わりません。マージ済みの修正が、呼び出しに応答していたコピーが main より古かったために機能していなかったことが2回ありました（#125、#158）。数時間後に、ツールのバグに見える別の形で発覚しました。doctor はこの差を served-code-differs として報告します。ただし、doctor の検出結果を読むのは doctor の実行者だけなので、MCP サーバーはその差を応答自体に含めるようになりました。提供されているパッケージのハッシュが、棚の隣にある memshelf-mcp のチェックアウト（または $MEMSHELF_CHECKOUT）と異なる場合、すべてのエンベロープは成功・エラーを問わず、該当コード、両方の短縮ハッシュ、それぞれの場所を含む warning で始まります。コードが同一なら何も追加されません。比較対象となるチェックアウトがない場合も、呼び出しごとの応答には何も追加されませんが、initialize の指示に鮮度が不明であることと、それを確認する方法が記載されます。差異が意図的な場合は、MEMSHELF_FRESHNESS_WARNING=0 で呼び出しごとの警告を無効にできます。

各ルールの設計根拠は docs/DECISIONS.md と docs/ARCHITECTURE.md に記載されています。

ひとつのメモリを複数の AI で共有

このメモリがベンダーを問わず利用できることは、設計上の意図ではなく、測定によって確認された事実です。ひとつの稼働中の棚が、ひとつの shelf-spec サーバーを介して Claude Code （Anthropic）と Gemini CLI（Google）によって読み取られ、相互に書き込まれています。プロトコルとフィールドの詳細は docs/portability.md を参照してください。

ステータス

M0 は完了しました。稼働中の棚で、コードを一切使わずにこのパターンを検証しました — 数か月分の資料を遡ってインポートし、その後1週間、終了時に棚へ格納しました （docs/M0.md）。M1 では、このパターンを適用するサーバー／CLIと Claude Code プラグインをリリースしました。完了条件を含む次のマイルストーン： docs/ROADMAP.md。リリース履歴： CHANGELOG.md。

ドキュメント

レンダリング済みサイト：https://ignatenkofi.github.io/memshelf-mcp/ — dogfood シェルフの週次レポートのインフォグラフィックも掲載しています。

ドキュメント	内容
docs/MANIFEST.md	課題、仮説、主要なシナリオ、原則、対象外の項目
docs/tools.md	ツールリファレンス：すべての memshelf_* ツールの詳細な説明（MCP スキーマには短い説明のみ記載）
docs/ARCHITECTURE.md	エピソード形式、ダイジェストの仕様、ストレージモード、トリガー、MCP ツールの概要、ポータビリティモデル、プライバシー、障害モード
docs/LANDSCAPE.md	先行事例の調査（2026-07）、プラットフォーム組み込み機能、位置付け、リスク
docs/ROADMAP.md	完了基準を含むマイルストーン M0～M3
docs/DECISIONS.md	意思決定ログ
docs/M0.md	M0 の実験プロトコルと結果：ケース、トークン台帳、想起テスト
docs/demo.md	dogfood シェルフで測定した数値：圧縮、想起テスト、doctor の調査結果
docs/portability.md	1つのメモリーを複数の AI で使う：ベンダー横断実験
docs/chat-projects.md	フックなしで使う Claude Desktop と claude.ai のプロジェクト：セットアップ、想起、シェルフへの保存、インデックスの最新状態の維持
docs/examples/	エピソードファイルとメモリーシェルフの INDEX の作成例
adapters/claude-code/	Claude Code プラグイン：/shelve スキル + SessionStart/SessionEnd/PreCompact フック
adapters/claude-desktop/	Claude Desktop .mcpb 拡張機能：ビルダー、バンドルチェッカー、デフォルトシェルフ設定
adapters/claude-account/	claude.ai アカウントスキルの正本のミラー — インストール不可で、比較用に存在します

プロジェクトのメモリーシェルフ

shelf/ は、このプロジェクト独自のメモリーシェルフであり、提供するツールを自ら使う dogfooding の場です。意思決定、却下した選択肢とその理由を含むセッションエピソードを記録しています。ここで過去の作業について何かを述べる前に、shelf/INDEX.md を読み、そこから参照されているエピソードを取得してください。過去の意思決定について推測することは、見積もりではなく不具合です。派生ファイル（ledger.tsv、INDEX.md、stats.svg、.meta.json）は、エピソードと同じコミットで書き込まれ（memshelf rebuild --shelf shelf）、shelf-pr-guard ワークフローは、それらに不整合がある PR または main への push を失敗させます。

起源

docshelf-mcp リポジトリで RFC-0001 として設計されました （#42、 #43、 #44）。2026-07-13 以降、このリポジトリがプロジェクトの本拠地です。docshelf 側のコピーは、歴史的スナップショットとして凍結されています。

関連プロジェクト

• docshelf-mcp — 姉妹プロジェクトであり、ストレージ層です。PDF／Markdown を、同じインデックス・取得方式でチャットプロジェクトから使いやすいドキュメントシェルフに変換します（測定値：質問あたり約 3.7K トークン対 1.2M）。memshelf は同リポジトリの RFC-0001 として生まれ、同じ分割器／インデクサー／読み取り／検索をそのまま再利用しています。
• dogfood メモリーシェルフは、設計上、非公開リポジトリです（MANIFEST の原則 5）。

ライセンス

MIT — LICENSE を参照してください。

---

mcp-name: io.github.ignatenkofi/memshelf-mcp