プロトタイプ · プレビュー版:公式レジストリのすべてのサーバーを掲載し、30分ごとに同期しています。Google でログインするとレビューを書けます。プロトタイプ · 30分ごとに更新
PopNx MCPAIを使う人のためのMCPサーバー · やさしい言葉で解説

Memshelf MCP

作者:ignatenkofiバージョン 0.4.0i★ 0iパソコンで動く公式サイト ↗
レジストリ名io.github.ignatenkofi/memshelf-mcp

インストール方法

What it does

Working memory for AI agents: digest-indexed episodes on a git shelf, recalled a section at a time.

  • Connects パソコンで動く
  • Account or key No key needed
  • Category 検索・AIの記憶

一緒に使える

この種の作業を AI に教える Skill。これと一緒に使えます

timesfm

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

作者:google-research★ 35,6291 個の skill

Skill · 手順書

Shadowbroker

Open-source intelligence for the global theater. Track everything from the corporate/private jets of the wealthy, and spy satellites, to seismic events in one unified interface. Hook an AI agent up to have it parse through data and find previously unseen correlations. The knowledge is available to…

作者:BigBodyCobain★ 11,6021 個の skill

Skill · 手順書

google-maps-scraper

scrape data from Google Maps. Extracts data such as the name, address, phone number, website URL, rating, reviews number, latitude and longitude, reviews,email and more for each place

作者:gosom★ 8,2091 個の skill

Skill · 手順書

この順位の理由

一覧は利用スコア(100 点満点)で並びます。内訳は次のとおり

人気0/80GitHub スターか週間ダウンロード数。大きい方を 60、小さい方を 20 で数えます
新しさ12/1230 日以内のリリースかコード更新で満点
応答中0/8前回の確認でクラウドのエンドポイントが応答
利用スコア12/100

品質: 基本チェック 3/3 項目に合格(表示のみ、並び順には不使用) · 勢い: データなし (「急上昇」タブでのみ使用)

インストール

使っているAIアプリを選んで、設定をコピーしてください。

ひとことで AI にインストールしてもらう

Memshelf MCP をインストールして。https://mcp.popnx.com/i/ignatenkofi-memshelf-mcp.md に従い、コマンドを見せて、私が OK するまで実行しないで。

パソコンで作業できる AI(Claude Code や Cursor など)に貼り付けます。手順を読み、コマンドを見せて、あなたの OK を待ちます。キー不要・登録不要。 · AI が読む全文を見る

チェック 3/3 合格 · あなたのパソコンで動きます · ✓ コマンド確認済み 2026年11月14日

まず:どの AI を使っていますか?

使っているアプリを選ぶと、下に手順が表示されます。

Claude につなげますが、先に準備が必要です

先にパソコンへ Python (uv) を入れてください(1 回だけ) · パソコン版 Claude アプリ(Windows または Mac)のみ。Web やスマホでは使えません

AI にインストールしてもらう

このメッセージを Claude のチャットに貼り付けます。AI がパソコンを確認し、変更するファイルを伝え、毎回あなたの了承を待ちます。

このパソコンの Claude に MCP server Memshelf MCP を入れてください。順番に:1) uv --version で uv があるか確認。なければ https://docs.astral.sh/uv/getting-started/installation/ から入れるよう私に伝え、自分では入れない。2) この設定だけを使う(PopNx MCP の確認済み):{ "mcpServers": { "memshelf": { "command": "uvx", "args": [ "memshelf-mcp" ] } } } 3) 変更するファイルのフルパスか実行するコマンドを伝えて、私の了承を待つ。4) キーは不要。5) 了承した内容を実行し、Memshelf MCP のツールが本当に表示されるか確認する。

このメッセージにあなたのキーは含まれません。キーが必要な場合は、AI がファイルやアプリの入力欄にご自身で貼るよう案内します。

  1. uv を入れる(まだなければ)

    もう入っていますか?先に確認 · ターミナルを開き、このコマンドを入力して Enter

    uv --version
    • バージョン番号(例 uv …)が出る = 入っています。この手順は飛ばせます
    • "command not found"(Windows では "is not recognized")が出る = まだ入っていないか、入れた直後でターミナルを開き直す必要があります
    ターミナルの開き方

    Mac:⌘ + Space を押し、Terminal と入力して Enter

    Windows:スタートメニューを開き、Windows PowerShell と入力して「開く」

    まだ入っていない場合: uv にはクリック式のインストーラーがありません。uv 公式ページからお使いの OS(macOS か Windows)用の 1 行コマンドをコピーしてターミナルに貼り付けます · Python を別に入れる必要はなく、必要なときに uv が自動で取得します

    uv のダウンロードページを開く ↗

    入れ終わったらターミナルを閉じて開き直し、同じコマンドをもう一度実行します。バージョン番号が出れば完了です: uv --version

    一度入れれば、uv を使うすべてのツールで使えます

  2. パソコン版 Claude アプリの設定ファイルを開く

    SettingsDeveloperEdit Config

  3. この設定を貼り付けて保存

    {
      "mcpServers": {
        "memshelf": {
          "command": "uvx",
          "args": [
            "memshelf-mcp"
          ]
        }
      }
    }
  4. Claude を終了してもう一度開く

  5. 試してみる

    Memshelf MCP を使って、私に何ができるか教えて、1 つやってみせて

    ✓ Claude が Memshelf MCP を使っていると言うか、回答に Memshelf MCP のツール名が出れば接続成功です

メニュー名は 2026年11月11日 に Anthropic のヘルプページで確認 · アプリのバージョンにより画面が少し違うことがあります

ChatGPT はまだ Memshelf MCP につなげません

Memshelf MCP はパソコンに入れて使うものですが、ChatGPT は Web 上で動くサーバーにしかつなげません

代わりにできること

A · Memshelf MCP につなげるアプリを使う

  • 先にパソコンへ Python (uv) を入れてください(1 回だけ) · パソコン版 Claude アプリ(Windows または Mac)のみ。Web やスマホでは使えません
  • 先にパソコンへ Python (uv) を入れてください(1 回だけ)
  • 先にパソコンへ Python (uv) を入れてください(1 回だけ)
  • 先にパソコンへ Python (uv) を入れてください(1 回だけ)

B · 検索・AIの記憶 の中で ChatGPT につなげる別のサーバー

同じカテゴリでよく使われているものから、キーなしでアドレスだけでつなげるものを選びました

Claude Code につなげますが、先に準備が必要です

先にパソコンへ Python (uv) を入れてください(1 回だけ)

AI にインストールしてもらう

このメッセージを Claude Code のチャットに貼り付けます。AI がパソコンを確認し、変更するファイルを伝え、毎回あなたの了承を待ちます。

このパソコンの Claude Code に MCP server Memshelf MCP を入れてください。順番に:1) uv --version で uv があるか確認。なければ https://docs.astral.sh/uv/getting-started/installation/ から入れるよう私に伝え、自分では入れない。2) この設定だけを使う(PopNx MCP の確認済み):claude mcp add --scope user memshelf -- uvx memshelf-mcp 3) 変更するファイルのフルパスか実行するコマンドを伝えて、私の了承を待つ。4) キーは不要。5) 了承した内容を実行し、Memshelf MCP のツールが本当に表示されるか確認する。

このメッセージにあなたのキーは含まれません。キーが必要な場合は、AI がファイルやアプリの入力欄にご自身で貼るよう案内します。

  1. uv を入れる(まだなければ)

    もう入っていますか?先に確認 · ターミナルを開き、このコマンドを入力して Enter

    uv --version
    • バージョン番号(例 uv …)が出る = 入っています。この手順は飛ばせます
    • "command not found"(Windows では "is not recognized")が出る = まだ入っていないか、入れた直後でターミナルを開き直す必要があります
    ターミナルの開き方

    Mac:⌘ + Space を押し、Terminal と入力して Enter

    Windows:スタートメニューを開き、Windows PowerShell と入力して「開く」

    まだ入っていない場合: uv にはクリック式のインストーラーがありません。uv 公式ページからお使いの OS(macOS か Windows)用の 1 行コマンドをコピーしてターミナルに貼り付けます · Python を別に入れる必要はなく、必要なときに uv が自動で取得します

    uv のダウンロードページを開く ↗

    入れ終わったらターミナルを閉じて開き直し、同じコマンドをもう一度実行します。バージョン番号が出れば完了です: uv --version

    一度入れれば、uv を使うすべてのツールで使えます

  2. ターミナルを開く

    Mac:Command+スペースで Terminal と入力 · Windows:PowerShell を開く

  3. このコマンドを貼り付けて Enter

    claude mcp add --scope user memshelf -- uvx memshelf-mcp
  4. Claude Code で /mcp と入力

    Memshelf MCP が一覧にあり、接続済みと表示されれば OK です

  5. 試してみる

    Memshelf MCP を使って、私に何ができるか教えて、1 つやってみせて

    ✓ Claude Code が Memshelf MCP を使っていると言うか、回答に Memshelf MCP のツール名が出れば接続成功です

メニュー名は 2026年11月11日 に Anthropic のヘルプページで確認 · アプリのバージョンにより画面が少し違うことがあります

Cursor につなげますが、先に準備が必要です

先にパソコンへ Python (uv) を入れてください(1 回だけ)

AI にインストールしてもらう

このメッセージを Cursor のチャットに貼り付けます。AI がパソコンを確認し、変更するファイルを伝え、毎回あなたの了承を待ちます。

このパソコンの Cursor に MCP server Memshelf MCP を入れてください。順番に:1) uv --version で uv があるか確認。なければ https://docs.astral.sh/uv/getting-started/installation/ から入れるよう私に伝え、自分では入れない。2) この設定だけを使う(PopNx MCP の確認済み):{ "mcpServers": { "memshelf": { "command": "uvx", "args": [ "memshelf-mcp" ] } } } 3) 変更するファイルのフルパスか実行するコマンドを伝えて、私の了承を待つ。4) キーは不要。5) 了承した内容を実行し、Memshelf MCP のツールが本当に表示されるか確認する。

このメッセージにあなたのキーは含まれません。キーが必要な場合は、AI がファイルやアプリの入力欄にご自身で貼るよう案内します。

  1. uv を入れる(まだなければ)

    もう入っていますか?先に確認 · ターミナルを開き、このコマンドを入力して Enter

    uv --version
    • バージョン番号(例 uv …)が出る = 入っています。この手順は飛ばせます
    • "command not found"(Windows では "is not recognized")が出る = まだ入っていないか、入れた直後でターミナルを開き直す必要があります
    ターミナルの開き方

    Mac:⌘ + Space を押し、Terminal と入力して Enter

    Windows:スタートメニューを開き、Windows PowerShell と入力して「開く」

    まだ入っていない場合: uv にはクリック式のインストーラーがありません。uv 公式ページからお使いの OS(macOS か Windows)用の 1 行コマンドをコピーしてターミナルに貼り付けます · Python を別に入れる必要はなく、必要なときに uv が自動で取得します

    uv のダウンロードページを開く ↗

    入れ終わったらターミナルを閉じて開き直し、同じコマンドをもう一度実行します。バージョン番号が出れば完了です: uv --version

    一度入れれば、uv を使うすべてのツールで使えます

  2. このボタンで Cursor を開く

    Cursor で開く

    Cursor がインストールの確認をするので Install を押します

  3. Cursor の AI チャットを Agent モードで開く

  4. 試してみる

    Memshelf MCP を使って、私に何ができるか教えて、1 つやってみせて

    ✓ Cursor が Memshelf MCP を使っていると言うか、回答に Memshelf MCP のツール名が出れば接続成功です

メニュー名は 2026年11月11日 に Cursor のヘルプページで確認 · アプリのバージョンにより画面が少し違うことがあります

VS Code につなげますが、先に準備が必要です

先にパソコンへ Python (uv) を入れてください(1 回だけ)

AI にインストールしてもらう

このメッセージを VS Code のチャットに貼り付けます。AI がパソコンを確認し、変更するファイルを伝え、毎回あなたの了承を待ちます。

このパソコンの VS Code に MCP server Memshelf MCP を入れてください。順番に:1) uv --version で uv があるか確認。なければ https://docs.astral.sh/uv/getting-started/installation/ から入れるよう私に伝え、自分では入れない。2) この設定だけを使う(PopNx MCP の確認済み):{ "servers": { "memshelf": { "type": "stdio", "command": "uvx", "args": [ "memshelf-mcp" ] } } } 3) 変更するファイルのフルパスか実行するコマンドを伝えて、私の了承を待つ。4) キーは不要。5) 了承した内容を実行し、Memshelf MCP のツールが本当に表示されるか確認する。

このメッセージにあなたのキーは含まれません。キーが必要な場合は、AI がファイルやアプリの入力欄にご自身で貼るよう案内します。

  1. uv を入れる(まだなければ)

    もう入っていますか?先に確認 · ターミナルを開き、このコマンドを入力して Enter

    uv --version
    • バージョン番号(例 uv …)が出る = 入っています。この手順は飛ばせます
    • "command not found"(Windows では "is not recognized")が出る = まだ入っていないか、入れた直後でターミナルを開き直す必要があります
    ターミナルの開き方

    Mac:⌘ + Space を押し、Terminal と入力して Enter

    Windows:スタートメニューを開き、Windows PowerShell と入力して「開く」

    まだ入っていない場合: uv にはクリック式のインストーラーがありません。uv 公式ページからお使いの OS(macOS か Windows)用の 1 行コマンドをコピーしてターミナルに貼り付けます · Python を別に入れる必要はなく、必要なときに uv が自動で取得します

    uv のダウンロードページを開く ↗

    入れ終わったらターミナルを閉じて開き直し、同じコマンドをもう一度実行します。バージョン番号が出れば完了です: uv --version

    一度入れれば、uv を使うすべてのツールで使えます

  2. このボタンで VS Code を開く

    VS Code で開く

    VS Code がインストールの確認をするので Install を押します

  3. VS Code の AI チャットを Agent モードで開く

  4. 試してみる

    Memshelf MCP を使って、私に何ができるか教えて、1 つやってみせて

    ✓ VS Code が Memshelf MCP を使っていると言うか、回答に Memshelf MCP のツール名が出れば接続成功です

メニュー名は 2026年11月11日 に VS Code のヘルプページで確認 · アプリのバージョンにより画面が少し違うことがあります

Windsurf、Zed、Gemini CLI など MCP を使える他のアプリは追加方法がそれぞれ違います。アプリ一覧で確認してください

MCP を使えるアプリをすべて見る →

JSON 設定は下の「開発者向け」にあります

つまずいたら?Memshelf MCP を使っている人に聞いてみましょう💬 ディスカッション →
開発者向け:ターミナルのコマンドと JSON 設定

パソコンにインストール

Claude Code

claude mcp add --scope user memshelf -- uvx memshelf-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "memshelf": {
      "command": "uvx",
      "args": [
        "memshelf-mcp"
      ]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "memshelf": {
      "command": "uvx",
      "args": [
        "memshelf-mcp"
      ]
    }
  }
}

VS Code (mcp.json)

{
  "servers": {
    "memshelf": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "memshelf-mcp"
      ]
    }
  }
}

この設定は、作者のレジストリ登録情報から作成しています。READMEと違う場合は、READMEに従ってください。

ひと目でわかる

週あたりのダウンロードi
34/週
接続方法
パソコンで動く
最新バージョンi
0.4.0
レジストリ公開日i
2026年10月7日
コードの最終更新i
2026年10月27日
作者
ignatenkofi
パッケージ
pypi: memshelf-mcp
ウェブサイト
ignatenkofi.github.io
レジストリでの状態
有効

使えるアプリ

このサーバーのつなぎ方と、各アプリの公式ドキュメントに基づきます。2026年11月10日に確認。

パソコン上で動かせるアプリ

ClaudeGooseLM StudioMsty StudioCherry StudioCursorVS Code + GitHub CopilotVisual StudioWindsurf (Devin Desktop)ZedKiroClineContinueJetBrains AI AssistantClaude CodeCodex CLIGemini CLIOpenCodenodecodeWarpLibreChatRaycast

すべてのアプリと長所・短所 →

できること

パソコンで動くサーバーです。インストールすると、ツール一覧がAIアプリに表示されます。

基本チェックi

誰でも見られる情報をチェックしており、コードは読んでいません。当てはまらない項目は数に入れていません。 · 2026年11月19日にチェック

  • ✓ 合格

    作者とリポジトリが一致

    レジストリ名は、リポジトリを所有するGitHubアカウント ignatenkofi で確認済みです

  • ✓ 合格

    今もメンテナンスされている

    コードの最終更新:23 日前

  • ✓ 合格

    ライセンスがある

    MITを使用

  • – 対象外

    エンドポイントが応答する

    これはパソコンで動くため、インターネット上のエンドポイントはありません

  • – 対象外

    OAuthでサインイン

    パソコンで動き、代わりにローカルの設定を使います

  • … 未チェック

    ツールの説明に隠れた指示がない

    パソコンで動くサーバーです。ツール一覧を読み取れるのは、インターネット上のエンドポイントがある場合だけです

公開済みの脆弱性(OSV.dev)

OSV.dev に memshelf-mcp@0.4.0 の登録はありません

このバージョンのパッケージ本体のみ確認。すべての依存関係ではありません · 確認日 2026年11月15日

確認していること → · JSON

作者の方へ:再確認の依頼・情報の誤りの報告
作者向け:README にバッジを付ける

作者の方は、このコードを README に貼れます。バッジはこのページにリンクします。

[![Featured on PopNx MCP](https://mcp.popnx.com/badge/ignatenkofi-memshelf-mcp.svg)](https://mcp.popnx.com/en/servers/ignatenkofi-memshelf-mcp)

話し合い

質問、コツの共有、使えないことの報告ができます。「役に立った」の多い順です。

まだ投稿はありません。最初の質問や共有をどうぞ。

ここの投稿は利用者によるもので、PopNx チームのものではありません。

ログインして投稿

ユーザーレビュー

まだレビューはありません

ログインしてレビューを書く

検索・AIの記憶のほかのサーバーとの比較i

  • このカテゴリのほかの6394件のうち0%よりスターが多い
  • このカテゴリのほかの6394件のうち47%より最近レジストリに公開
  • 基本チェックの結果が、このカテゴリのほかの6394件のうち99%と同じかそれ以上

レジストリでこのカテゴリにある有効なすべてのサーバーと比較しています。スターは、公開者がリポジトリの所有者である場合だけ数えます。

よくある質問

Memshelf MCPは安全ですか?

当てはまる基本チェック3項目のうち3項目に合格しました。コードは読んでいません。キーやトークンを追加する前に、サーバーがどんなアクセスを求めているかを確認し、必要な権限だけを持つキーを使ってください。

どんなキーやコードが必要ですか?

レジストリには必須のキーは載っていません。ただし、最初に使うときにサインインを求めるサーバーもあります。

パソコンで動きますか、それともクラウドですか?

あなたのパソコンで動きます。必要なときにAIアプリが起動し、データは作者のサーバーを通りません(サーバー自体がオンラインサービスを呼び出す場合を除きます)。

今もメンテナンスされていますか?

GitHubリポジトリの最終更新は23 日前、最新バージョン(0.4.0)がレジストリに届いたのは43 日前です。

どのアプリで使えますか?

Claude Desktop、Claude Code、Cursor、VS CodeなどのMCP対応アプリで使えます。パソコンにPython (uv)も必要です。

代わりに使えるものは?

同じカテゴリには:OpenSEO, Exa, Microsoft Learn MCP, Docs, COTAL actions (cotal.ai)

似た働きのほかの候補

同じカテゴリでほかの作者のもの。コマンドは確認済み。公式を先に、次にスター順。

カードの見方:↓ 週あたりのダウンロードi★ GitHubスターi3つの柱:レビュー · チェック · 利用状況i更新=最新バージョンをレジストリに公開した日i

OpenSEO

Keyword research, site audits, rank tracking and AI visibility for your AI agent.

作者:every-app広く使われている★ 2.8万5 日前更新

クラウドで動く✓ everyapp.com

Exa

Connect AI agents to Exa for web search, content fetching, and multi-step research.

作者:exa-labs広く使われている★ 52422 か月前更新

クラウドで動く✓ 提供元 · exa.aiPopNx チームが実際に試用

Microsoft Learn MCP

Official Microsoft Learn MCP Server – real-time, trusted docs & code samples for AI and LLMs.

作者:MicrosoftDocs広く使われている★ 199712 か月前更新

クラウドで動く✓ 提供元 · microsoft.comPopNx チームが実際に試用

Docs

Search and read Empryo's documentation. Read-only, no auth, no local access.

作者:proxysoul成長中★ 16262 か月前更新

クラウドで動く✓ empryo.com
似たものと比べる
これ
Memshelf MCP
OpenSEOExaMicrosoft Learn MCPDocsCOTAL actions (cotal.ai)
動く場所パソコンにインストールが必要クラウドで動き、インストール不要クラウドで動き、インストール不要クラウドで動き、インストール不要クラウドで動き、インストール不要クラウドで動き、インストール不要
キーが必要いいえいいえいいえいいえいいえいいえ
Claude で + から追加いいえはいはいはいいいえいいえ
基本チェック3/35/52/44/44/44/4
ライセンスMITMITMITCC-BY-4.0NOASSERTIONApache-2.0
料金登録情報に費用の記載なし登録情報に費用の記載なし登録情報に費用の記載なし登録情報に費用の記載なし登録情報に費用の記載なし登録情報に費用の記載なし

作者のREADME

READMEを開く

作者のリポジトリから書かれたとおりにコピーしたものです。PopNx MCPは内容を確認・推奨していません。HTML、画像、スクリプトは取り除いています。リンクはこのサイトの外へ移動します。

memshelf-mcp

Put your agent's memory on a shelf, hand it the index.

                              _          _  __

_ _ ___ _ _ _| | ___| |/ _| | '_ _ \ / _ \ '_ _ \/ __| '_ \ / _ \ | |_ | | | | | | / | | | | \ \ | | | __/ | _| |_| |_| |_|\___|_| |_| |_|___/_| |_|\___|_|_|


| INDEX >> | E-01 | E-02 | E-03 | E-04 | ... | |________|__|__|__|__|___| memory shelves for AI agents

What this is

Long-running agent sessions burn tokens re-sending history and lose detail to lossy auto-compaction. memshelf applies the docshelf pattern — tiny index in context, bodies fetched on demand — to the agent's own working memory:

  1. Closed conversation topics, research dumps, and bulky tool output are offloaded to a local shelf as Markdown episodes.
  2. Each episode carries an LLM-written, contract-validated digest that preserves decisions, rejected alternatives, artifacts, and open threads.
  3. The agent keeps only INDEX.md (kilobytes) + digests in context and recalls exact sections via INDEX → episode → section slice over MCP.

Positioning in one sentence: *claude-mem's loop, git's substrate, docshelf's navigation* — episodic memory you can grep, diff, review, and carry between hosts. Private and local by default: the standard storage mode is a local git repo with no remote configured. The tool is public; the memory never is.

Measured, not promised

One week of dogfooding on the live shelf — full numbers and methodology in docs/demo.md:

MeasureResult
Episodes on the shelf34
Standing cost in every session (INDEX + digests)~8.6K tokens
Shelved mass those episodes replace~1.9M tokens — ≈220 : 1
One question answered from memory~1.8K tokens (INDEX + one episode)
Recall test: fresh agent, INDEX path only5 / 5 — zero misses, zero over-fetch

Tokens are counted as chars/4 everywhere, so the *ratios* are estimator-independent; absolute counts move with the tokenizer.

Quick start

As an MCP server:

# Claude Code

claude mcp add memshelf -- uvx memshelf-mcp

// Claude Desktop (claude_desktop_config.json)

{ "mcpServers": { "memshelf": { "command": "uvx", "args": ["memshelf-mcp"] } } }

As a Claude Desktop extension — adapters/claude-desktop/: an .mcpb bundle installed from *Settings → Extensions*, with a Default shelf setting so calls need not repeat the path. Nothing has to be installed alongside it — not even Python.

As a Claude Code plugin — adapters/claude-code/: a /shelve skill plus SessionStart / SessionEnd / PreCompact hooks.

Or from the shell (pip install memshelf-mcp, Python ≥ 3.10) — the same loop, no 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]' adds an embedding sidecar so search also finds paraphrases and the other language (memshelf semantic build --shelf ~/my-shelf once; MEMSHELF_SEMANTIC=off turns it off). Optional: the base install stays grep-only and as light as it is.

Tool surface

One verb per job; the same names over MCP (memshelf_*) and in the CLI (long-form descriptions: docs/tools.md):

ToolWhat it does
initCreate (or top up) a memory shelf: docshelf layout, fixed categories
shelveOffload one closed topic as a durable, indexed episode; --amend rewrites in place
lint_digestValidate a digest against the contract without touching the shelf
importRetro-shelve a whole exported dialog without pulling it through context
indexReturn the shelf INDEX — the small recall entry point
recallFetch an episode by id, or a single ## Section of it
searchGrep the shelf; returns matching episodes
statsThe shelf's token economy: standing cost vs shelved mass, claimed vs realized
adviseWhat your context is made of and what you could put down — proposals only
rebuildRegenerate every derived file from the episodes
rollupArchive a period behind one digest-of-digests
purgeDrop episodes past retain_until, then reindex — dry run by default
resolveSettle multi-writer conflicts: regenerate derived, union the recall log
doctorDiagnose: episode schema, digest contract at rest, secret shapes, index bloat
freshnessCLI only — which installed consumer (pipx, Desktop extension) answers calls, and what is merged but unreleased (#125)
syncCLI only — fetch and fast-forward the shelf clone to its remote (#157)
prune-splitsCLI only — remove H2 split directories git never got (migration for #109)
tagsCLI only — episodes grouped by frontmatter tag (#18)
graphCLI only — who mentions whom: cross-episode id references as JSON or Mermaid (#18)
retroCLI only — one quarter of the shelf as a Markdown retrospective (#18)
forkCLI only — bootstrap a fresh session from INDEX + selected episodes or sections (#18)
mirrorCLI only — INDEX (± episodes) as one self-contained HTML page for phone-side reading (#18)
semanticCLI only — build / status / drop the embedding sidecar that turns search hybrid; lives outside the shelf, needs pip install 'memshelf-mcp[semantic]' (#17)
search-benchCLI only — hit@1 / hit@k / MRR of grep vs hybrid on a query expected-id file (#17)

The rules the tools enforce

The digest is a contract, not a convention. It is the only thing read at recall before fetching a body, so a weak one devalues the whole episode. lint_digest runs the same validator as shelve with no side effects (--strict turns warnings into failures); errors block a shelve, warnings do not — a pure reference digest legitimately carries no decision marker. A rejected digest is a feature: the tool prints exactly what to fix and writes nothing.

`--amend` re-runs the whole pipeline — redaction, the digest contract, composition — so an amended episode is exactly as guarded as a fresh one, which a hand-edit of the file never is. Amending a slug that is not on the shelf is an error, not a create.

The episode is the source; everything else is output. ledger.tsv, INDEX.md, stats.svg and each category's .meta.json are derived: shelve writes and commits the episode alone, rebuild renders the rest — delete all four and rebuild restores them byte-identically. That is what makes two sessions shelving in parallel a non-event: the merge is clean by construction. On a shared shelf, let a bot own the derived files on main — ready-to-copy workflows in adapters/shelf-repo/; rebuild --adopt migrates an older shelf once, rebuild --check is the CI guard.

Two consequences worth stating plainly, because getting them wrong costs a merge conflict:

  • `doctor` reports `no-ledger-row` and `stale-index` immediately after a correct `shelve` — on every branch, `main` included. Nothing is broken: the episode is written, the derived files are not rendered yet. They clear on the next rebuild — the bot's run, on a shelf that has one.
  • Do not rebuild and commit the derived files by hand to silence them. That is exactly the conflict class the split removes: a hand-regenerated ledger.tsv/INDEX.md/stats.svg meets the bot's, and the merge stops being clean by construction. Wait for the renderer; on a shelf without a bot, run memshelf rebuild --shelf . as its own step.

If those warnings persist for a *day* while episodes keep arriving, that is a different state — the renderer is not lagging, it is stopped — and doctor says so separately, as derived-stale at error severity. The day is counted from when the renderer could first see the work, not from the ledger's last commit: an episode pushed minutes ago onto a shelf whose ledger has not moved since yesterday says nothing about the renderer, and saying otherwise sent readers to a manual rebuild, which is the conflict this whole split exists to avoid.

That arrival is read from this clone's reflog for the tracked upstream — the one local record of *when the ref moved here*. A commit date is not a substitute: it says when the episode was written, and «shelve now, push when confirmed» is a documented way to work, so the two can be a working day apart. Where the reflog cannot say — a fresh clone starts an empty one, which is what CI and ephemeral agent sessions run in — doctor reports renderer-wait-unknown at the unknown level instead of picking a verdict: from there, «stopped» and «handed the work a minute ago» look the same, and the renderer has to be judged where it can be observed, on its own job's run. On a shelf with no upstream there is no renderer to be fair to, and the ledger's own age stays the clock.

The ref the renderer is judged by is the render branch, not whatever the checkout happens to track (#180). The bot renders one branch — the remote's default one, read as origin/HEAD when the clone has it, else origin/main, else origin/master — so a clone standing on a PR branch is not told derived-stale for an episode that sits on origin/ only. That episode waits for a merge, not for the renderer, and doctor says so with the warning upstream-not-rendered; one that did reach the render branch is judged there even from the PR branch, and a local commit on either stays episode-unpushed.

There was a third way to hold stale-index forever, and it is fixed rather than documented: docshelf split any episode past 50 KiB into section files beside it, shelve committed the episode alone, and from then on this working copy rendered an INDEX no other checkout could produce — no rebuild could clear it, and search answered with addresses that existed on one machine (#109). shelve no longer splits. A shelf that already carries such directories keeps reporting them as local-split-dir until memshelf prune-splits --shelf . --apply removes them; the episode file holds every section, so nothing is lost. It is a dry run without --apply, and a split directory that *is* committed is

冒頭だけを表示しています。続きはリポジトリで読めます