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

Handoff

作者:kirill-sviridovバージョン 0.4.0i★ 2iパソコンで動くリポジトリ ↗
レジストリ名io.github.kirill-sviridov/handoff-mcp

インストール方法

What it does

Cross-session memory for Claude over MCP — prioritised briefs, supersession, cross-project recall.

  • 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,6381 個の 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,6051 個の 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,2361 個の skill

Skill · 手順書

この順位の理由

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

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

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

インストール

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

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

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

このメッセージにあなたのキーは含まれません。キーが必要な場合は、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": {
        "handoff": {
          "command": "uvx",
          "args": [
            "handoff-mcp"
          ]
        }
      }
    }
  4. Claude を終了してもう一度開く

  5. 試してみる

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

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

追加の設定 2 項目(入力しなくても使えます)

上のコマンドはこれらがなくても動きます。変えたいときだけ作者の説明に沿って追加してください。

  • HANDOFF_VAULT すべてのプロジェクトで共有する markdown vault へのパス(vault は 1 つ)。
    英語の原文を見るPath to the shared markdown vault (one vault across all projects).
    · 初期値 ~/.handoff-mcp/vault
  • HANDOFF_PROJECT 共有 vault 内の、このエージェント/リポジトリのプロジェクト名前空間。
    英語の原文を見るProject namespace for this agent/repo within the shared vault.

説明は自動翻訳です。変数名は原文のままです。迷ったら原文を確認してください。

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

ChatGPT はまだ Handoff につなげません

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

代わりにできること

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

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

このメッセージにあなたのキーは含まれません。キーが必要な場合は、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 handoff -- uvx handoff-mcp
  4. Claude Code で /mcp と入力

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

  5. 試してみる

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

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

追加の設定 2 項目(入力しなくても使えます)

上のコマンドはこれらがなくても動きます。変えたいときだけ作者の説明に沿って追加してください。

  • HANDOFF_VAULT すべてのプロジェクトで共有する markdown vault へのパス(vault は 1 つ)。
    英語の原文を見るPath to the shared markdown vault (one vault across all projects).
    · 初期値 ~/.handoff-mcp/vault
  • HANDOFF_PROJECT 共有 vault 内の、このエージェント/リポジトリのプロジェクト名前空間。
    英語の原文を見るProject namespace for this agent/repo within the shared vault.

説明は自動翻訳です。変数名は原文のままです。迷ったら原文を確認してください。

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

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

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

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

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

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

このメッセージにあなたのキーは含まれません。キーが必要な場合は、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. 試してみる

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

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

追加の設定 2 項目(入力しなくても使えます)

上のコマンドはこれらがなくても動きます。変えたいときだけ作者の説明に沿って追加してください。

  • HANDOFF_VAULT すべてのプロジェクトで共有する markdown vault へのパス(vault は 1 つ)。
    英語の原文を見るPath to the shared markdown vault (one vault across all projects).
    · 初期値 ~/.handoff-mcp/vault
  • HANDOFF_PROJECT 共有 vault 内の、このエージェント/リポジトリのプロジェクト名前空間。
    英語の原文を見るProject namespace for this agent/repo within the shared vault.

説明は自動翻訳です。変数名は原文のままです。迷ったら原文を確認してください。

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

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

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

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

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

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

このメッセージにあなたのキーは含まれません。キーが必要な場合は、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. 試してみる

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

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

追加の設定 2 項目(入力しなくても使えます)

上のコマンドはこれらがなくても動きます。変えたいときだけ作者の説明に沿って追加してください。

  • HANDOFF_VAULT すべてのプロジェクトで共有する markdown vault へのパス(vault は 1 つ)。
    英語の原文を見るPath to the shared markdown vault (one vault across all projects).
    · 初期値 ~/.handoff-mcp/vault
  • HANDOFF_PROJECT 共有 vault 内の、このエージェント/リポジトリのプロジェクト名前空間。
    英語の原文を見るProject namespace for this agent/repo within the shared vault.

説明は自動翻訳です。変数名は原文のままです。迷ったら原文を確認してください。

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

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

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

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

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

パソコンにインストール

Claude Code

claude mcp add --scope user handoff -- uvx handoff-mcp

Claude Desktop (claude_desktop_config.json)

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

Cursor (~/.cursor/mcp.json)

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

VS Code (mcp.json)

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

自分で入力する値

  • HANDOFF_VAULT env
    すべてのプロジェクトで共有する markdown vault へのパス(vault は 1 つ)。
    英語の原文を見るPath to the shared markdown vault (one vault across all projects).
  • HANDOFF_PROJECT env
    共有 vault 内の、このエージェント/リポジトリのプロジェクト名前空間。
    英語の原文を見るProject namespace for this agent/repo within the shared vault.

説明は自動翻訳です。変数名は原文のままです。迷ったら原文を確認してください。

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

ひと目でわかる

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

使えるアプリ

このサーバーのつなぎ方と、各アプリの公式ドキュメントに基づきます。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アカウント kirill-sviridov で確認済みです

  • ✓ 合格

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

    コードの最終更新:2 か月前

  • ✓ 合格

    ライセンスがある

    MITを使用

  • – 対象外

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

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

  • – 対象外

    OAuthでサインイン

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

  • … 未チェック

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

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

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

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

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

確認していること → · JSON

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

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

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

話し合い

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

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

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

ログインして投稿

ユーザーレビュー

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

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

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

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

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

よくある質問

Handoffは安全ですか?

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

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

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

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

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

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

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

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

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広く使われている★ 52442 か月前更新

クラウドで動く✓ 提供元 · 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
似たものと比べる
これ
Handoff
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、画像、スクリプトは取り除いています。リンクはこのサイトの外へ移動します。

handoff-mcp

Your agent's memory between sessions. Persistent, cross-project hand-off for

Claude over the Model Context Protocol — it remembers the goal, the decisions,

the dead-ends, and what's next, so the next session never starts from zero.

Claude forgets everything between sessions. handoff-mcp gives it a memory that survives the context window: it tracks the *progress* of your work — goals, decisions and their rationale, dead-ends, open questions, the next step — and at the boundary of a session produces a prioritised, token-budgeted brief so the next session resumes already knowing where you left off.

It is not a context dump. Two things make it different from similarity-based memory stores (mem0 / OpenMemory style):

  1. Temporal supersession. A new decision retracts an old one; retracted decisions never appear in a future brief. Memory reflects the *current* state of the world, not a flat pile of contradictory facts.
  2. Deterministic brief. The brief is assembled by an explainable ranker (recency + importance + supersession), not by an LLM — so it is reproducible and stays within a token budget (a soft cap on event content; see Limitations).
  3. Your store, multi-device. The vault is your own private git repo, not a hosted service — so memory can follow you across machines (pull-on-start, push-on-checkpoint, conflict-free entity merges) with zero vendor lock. See Multi-device sync.

Status: v0.4, early. The core (vault, brief, supersession, keyword search,

cross-project recall) is tested and stable; the semantic, consolidation,

importer, and multi-device sync layers are optional and newer. It leans on the agent calling the tools

at the right moments — see Limitations for the honest edges.

It is also cross-project: one vault, namespaced per project. The brief is project-scoped (where did I leave off *here*), but search_memory recalls across *all* projects — so when you say *"in one of my projects we did X"*, Claude can find and pull that decision out of another project.

Contents

  • Demo: two sessions
  • Benchmarks
  • How it works
  • MCP tools
  • Cost & API keys
  • Semantic recall (optional)
  • Memory consolidation (optional)
  • Import existing history
  • Quickstart
  • Connect your MCP client — Claude, Cursor, Codex, Kilo Code, …
  • Where your memory lives
  • Multi-device sync (optional)
  • Agent integration
  • Limitations
  • Development
  • License

Demo: two sessions

python examples/two_sessions_demo.py — session 1 works and stops; session 2 is a *fresh* process that resumes from the brief alone.

Session 1 logs its progress (and changes its mind once):

log_event("goal",     "Ship the finance agent: income/expense tracking…")

d = log_event("decision", "Store transactions in a flat JSON file.") log_event("decision", "Use SQLite instead of JSON — need queries.", supersedes=[d]) # retracts ↑ note_entity("Architecture", "SQLite-backed; LLM summary calls run in a worker.") # durable log_event("deadend", "Provider streaming API times out on long months; needs chunking.") log_event("question", "Recurring transactions: templates or materialised rows?") log_event("next_step","Write the SQLite schema, then the ingest function.") checkpoint("Chose SQLite; finance schema is next.")

Session 2 calls get_brief() and gets back only the *current* state — the retracted JSON decision is gone:

# Hand-off brief — agent-hub

Goal

  • Ship the finance agent: income/expense tracking with scheduled summaries.

Next step

  • Write the SQLite schema for transactions and categories, then the ingest function.

Decisions

  • Use SQLite for transactions instead of JSON — need queries for summaries. See [[Architecture]].

Dead ends (tried & failed)

  • Tried the provider's streaming API for the summary job — times out on long months. Don't retry without chunking.

Open questions

  • Should recurring transactions be modelled as templates or materialised rows?

Related knowledge

  • [[Architecture]] — SQLite-backed; LLM summary calls run in a worker.

The retracted "flat JSON file" decision never appears. The graph-linked

[[Architecture]] note is pulled in automatically. The brief is ~170 tokens.

And cross-project recall — search_memory("timeout chunking", scope="all") pulls a decision out of a *different* project:

- [hermes]    In the Hermes project we solved long-job timeouts by chunking requests.
  • [agent-hub] Tried the provider's streaming API for the summary job — times out on long months…

Benchmarks

Two offline, deterministic benchmarks — no LLM, no network — so they regenerate identically anywhere and are pinned by tests/test_benchmark.py. Full numbers, methodology, and how to reproduce: benchmarks/RESULTS.md.

1. Supersession in isolation (benchmarks/supersession_benchmark.py). A project's decisions evolve across 8 statements over 4 topics; each has one decision a later one retracts (JSON→SQLite, cookies→JWT, …). Retrieved by decision (so every stale fact is reachable), the flat log vs the active view:

modestale leakedcurrent kept
supersession OFF (flat log)4 / 44 / 4
supersession ON (active view)0 / 44 / 4

Supersession removes exactly the retracted decisions while keeping every current one — and scoring *current kept* too means an empty answer can't pass as a win. A similarity store with no notion of one fact retiring another behaves like the OFF row.

2. Brief vs naive dump (benchmarks/brief_reconstruction.py). What a resuming session actually reads — the budgeted, supersession-aware brief vs pasting back the whole log. As history grows the dump balloons and keeps carrying every retraction; the brief stays bounded (a soft cap) and contradiction-free while retaining all key items (e.g. at 228 events: 3063→217 tokens, 14×, 3 contradictions → 0).

These measure the mechanism honestly rather than staging a head-to-head against

another store — a fair cross-system run needs both under identical retrieval plus

an LLM endpoint we can't reproduce in CI (see

ADR-0008).

"Tokens" here and elsewhere in this README are estimated as len(text) / 4

(model-agnostic), not counted with a real tokenizer.

How it works

The markdown vault is the source of truth — human-readable, openable in Obsidian, your data on your disk. The SQLite + FTS5 index is *derived* from the vault and can be rebuilt at any time; it powers ranking, the token budget, and cross-project full-text search.

See docs/architecture.md and the ADRs for the design rationale.

MCP tools

ToolWhen Claude calls it
get_brief(project?, token_budget?)At session start — load where the last session left off.
log_event(type, content, importance?, supersedes?, supersedes_query?, project?)As work happens — record goals, decisions, dead-ends, files, questions, next steps. supersedes retires a prior event by id; supersedes_query retires the best-matching active event of the same type when you don't have its id (ADR-0007).
`search_memory(query, scope=current\all, limit?)`When the user references past or other-project work. limit caps the number of results (default 10). Each hit includes the event id, feedable straight into log_event's supersedes.
note_entity(name, content, project?)To record durable project knowledge (architecture, conventions, components).
checkpoint(summary?, project?)At session end — finalise the session and emit the brief. Pass the same project you logged under (defaults to the session's project).
consolidate(project?, older_than_days?)To compress old sessions into durable notes (opt-in, needs an LLM).
sync(remote_url?)To sync memory across devices — pull, commit, and push the vault's private git remote (opt-in). First call with a repo URL configures it; then a bare call syncs. See Multi-device sync.

Also exposed: an MCP resource session://brief and a prompt resume for auto-loading the brief at the top of a session.

log_event types: goal, decision, deadend, file, question, next_step.

Cost & API keys

No subscription. No required API keys. The core is free and fully local — your memory is plain files on your disk, and handoff-mcp never phones home (no hosted service, no telemetry).

CapabilityNeeds a model / key?
Memory, brief, supersession, keyword search, cross-project, importersNo — local, offline, free
Semantic recall *(optional)*No by default (hashing or local sentence-transformers); bring your own OpenAI-compatible key only if you pick the openai backend
Consolidation *(optional, occasional)*A model — your own key (a few cents, run rarely; it's not a hot path) or a local model

So most of the value costs nothing and needs no key. The optional layers either run locally or use *your own* provider — you're never locked into ours.

Semantic recall (optional)

Keyword search (FTS5/bm25) is the default and needs nothing extra. You can enable a semantic layer that fuses keyword and embedding similarity with Reciprocal Rank Fusion:

HANDOFF_SEMANTIC=1 handoff-mcp     # turn the layer on (default: hashing backend)

The backend you pick decides whether this actually understands paraphrases. The default hashing backend is a *lexical* baseline — it hashes tokens, so it adds fuzzy lexical matching (and demonstrates the hybrid pipeline) but does not recall on meaning when the words differ. For genuine paraphrase-tolerant recall, choose local or openai, which use learned embeddings.

Pluggable embedding backends, selected with HANDOFF_EMBEDDER — one server, no forks:

BackendInstallParaphrase?Notes
hashing (default)—No — lexicalDeterministic, offline, zero-dependency toy baseline (feature-hashing). Good for demos/tests; not real semantics.
local (recommended)pip install -e ".[semantic-local]"YesOffline sentence-transformers; no key, pulls in torch. Default model Qwen/Qwen3-Embedding-0.6B (multilingual incl. Russian, 1024-dim, Apache-2.0).
openaipip install -e ".[semantic-openai]"YesAny OpenAI-compatible endpoint (OpenAI, Together, a self-hosted proxy, …). Set HANDOFF_EMBED_BASE_URL / OPENAI_BASE_URL and HANDOFF_EMBED_API_KEY / OPENAI_API_KEY.
# Example: semantic recall via any OpenAI-compatible e

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