Apiary Memory

Apiary Memory MCP

別名： Apiary Memory · 记忆蜂巢 · Memory Hive · 蜂巢 · PyPI の apiary-memory および MCP Registry の io.github.330899935/apiary-memory（v0.2.0 以降） · 旧名称の memory-hive-mcp / hive-memory（v0.1.9 以前）も、引き続きインストールして使用できます。 hive.com（チームコラボレーション）や hive-mcp Claude Code プラグインとは関係ありません。

MCP を介して AI エージェントが使える、ローカルファーストの個人向けメモリーです。 エージェントは、あなたが確定した内容を検索し、残すべきだと考えるものを提案できます。ただし、確定できるのはあなただけです。 すべてのデータは自分のディスク上の1つのファイルに保存され、外部に送信されることはありません。

単独で動作します。すぐに使える SQLite メモリーストアがこのパッケージに含まれており、アカウント、クラウド、デーモン、依存関係は不要です。

pip install apiary-memory

デスクトップアプリで使用する場合、ターミナルは不要です： apiary-memory-0.2.0.mcpb をダウンロードして、ダブルクリックしてください。

2026-10-27 に、Hive をローカルで実行する1台の MacBook で測定しました。スクリプトと生の出力は bench/ にあります。

指標	結果
検索レイテンシー	p95 111 ms、p50 76 ms（ウォーム時、HTTP を含む）
検索結果	40 回の試行の 97.5% で正しいエントリーが上位5件以内
コーパス	1,303 エントリー · 2.39 M 文字 · 45 日分、プレーンテキストのみ

検索には各エントリー自身のタイトルをクエリとして使用しました。これは簡単な条件です。インデックスが完全であり、完全一致する語句で正しく順位付けされることを示していますが、自分の言葉で尋ねた質問にどれほど適切に答えられるかを示すものではありません。自分の Hive で bench/bench_search.py を実行してください。

---

アプリなしで使える機能

控えめながらも、メモリーサーバーとして一通りの機能を備えています。他に何もインストールされていないマシンでも、次のように動作します。

呼び出し	動作
initialize	ローカルで応答し、プロトコルは 2024-11-05
tools/list	ローカルで応答し、6つのツールを返します
propose	ディスク上の実際のデータベースに書き込みます
recall	そのデータベースを検索し、順位付けされたエントリーを返します
get_context	最近あなたが確定した内容のダイジェスト
manage	1件のエントリーの読み取り、保留中の項目の一覧表示、削除、復元
say / board	複数のエージェントが連携するための共有メッセージボード

ストレージは、デフォルトで ~/.memory-hive/hive.db にある SQLite データベースです。検索は字句ベースです。中国語には文字のバイグラム、ラテン文字には単語を使います。そのため、語句が重なる場合は適切に順位付けされますが、重ならない場合は見つかりません。埋め込みもベクトルインデックスもありません。どのエンジンが応答したか常に分かるよう、すべての応答に "mode": "local" が含まれます。

アプリなしの場合、データベースは通常の SQLite であり、暗号化されていません。 後で気付くことのないよう、ここに明記しています。詳しくは正直な制限をご覧ください。

アプリで追加される機能

macOS 用 Apiary Memory は、同じ設計に高コストな機能を組み込んだものです。8つの保管庫のうち4つは PIN でロックされ（Argon2id でラップされた鍵、保存時の AES-256）、日次の進化ログ、複数エージェントの ID 管理、閲覧・確定用の UI を備えています。また、より高度な順位付けで MCP 自体にも応答します。

アプリが起動していれば、このパッケージはアプリを使い、ローカルファイルには触れません。アプリが起動していなければ、ローカルストアが応答します。あらかじめどちらかを選ぶ必要はありません。

HIVE_MODE	動作
auto（デフォルト）	アプリに問い合わせます。アプリに接続できない場合のみローカルストアを使用します。
local	ネットワークには一切接続しません。常にローカルストアを使用します。
remote	アプリのみを使用します。接続に失敗した場合は、別の方法に切り替えずエラーになります。

どのモードでも、次のルールが適用されます。アプリが起動していてエラーを返した場合、そのエラーは変更せずに返されます。 拒否されたときにフォールバックすると、クライアントはアプリに接続したと思っているのに、メモリーが別のデータベースに書き込まれてしまうためです。データがひそかに分岐するより、エラーメッセージが表示される方が望ましいため、アプリからの応答が最終結果となります。フォールバックが実行されるのは接続に失敗した場合のみで、それ以外では実行されません。

インストール

pip install apiary-memory        # the server: apiary-memory (was apiary-memory)
                                 # the human's CLI: apiary-memory-cli (was apiary-memory-cli)

Python 3.8 以降が必要です。ほかにインストールするものはありません。このパッケージは標準ライブラリのみを使用し、sqlite3 もその一部です。

チェックアウトしたリポジトリから：

git clone https://github.com/330899935/apiary-memory
cd apiary-memory
PYTHONPATH=src python -m hive_mcp.stdio

クライアントを接続する

stdio コマンドを実行できる MCP ホストなら、どれでも動作します。必須なのはコマンドだけで、ほかはすべて任意です。

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "apiary-memory": {
      "command": "apiary-memory",
      "env": { "HIVE_MODE": "local" }
    }
  }
}

Cursor — ~/.cursor/mcp.json。mcpServers の形式は同じです。

HTTP のみを使用するホスト — アプリを起動し、ヘッダー X-Hive-Agent と X-Hive-Token を付けて http://127.0.0.1:8768/mcp に接続します。このパッケージが対応するのは stdio 経由です。HTTP エンドポイントはアプリに属します。

前提条件

ローカルストアには不要です — パッケージをインストールすれば動作します。アプリの実行が前提条件となるのは、暗号化されたボールト、進化ログ、マルチエージェントのアイデンティティなど、アプリ独自の機能を使う場合だけです。これらの機能を使うには、the Hive app（macOS、バージョン 1.4.5 以降）をインストールし、HIVE_MODE は auto のままにしてください。

6 つのツール

この 6 つのツールが、利用できるすべてです。アプリが応答する場合もローカルストアが応答する場合も同じ 6 つですが、異なるのは背後のランキング方式と、2 つの入力についてはツールが存在するかどうかです。アプリは事前計算済みの埋め込み（recall.query_vector、propose.vector）を受け付けます。ローカルストアには埋め込み生成機能がないため、ローカルストアが応答できる場合は、auto のもとでセッション途中にアプリが応答しなくなる可能性がある場合も含め、tools/list からこの 2 つの入力が省かれます。受け付けたうえで何もせず無視するようなフィールドは、そもそも表示しません。

同じルールは説明文にも適用されます。ローカルストアが応答できる場所では、recall.query はそのとおり、単語と文字の 2-gram を使う語彙ベースのランキング（埋め込みなし）として説明されます。アプリのみが応答できる場所では、query_vector を使ったアプリのインデックスベースのランキングとして説明されます。説明文は入力に対して何が起きるかを示すものなので、受け付ける入力に合わせて範囲を限定しています。

デフォルト値の範囲は限定せず、共有されます。limit を省略すると、recall は 10 件、get_context は 8 件を返します。compact を省略すると、本文は短縮されて返されます。say で ttl を省略すると、カードの有効期間は 24 時間です。デフォルト値は、一方のエンジンにない機能ではなくスキーマ内の数値なので、どちらのエンジンも同じ数値を返します。store.py ではそれぞれを名前付き定数として定義し、テストでは手書きの値をもう一つ用意するのではなく、応答を表示されている数値と比較します。

ツール	種類	用途
recall	読み取り	トピックを指定して、確認済みのメモリを検索します。{"query": "..."} に加えて、limit、vaults、compact を任意で指定できます。
propose	書き込み	人間の承認を得るためにメモリを提出します。キューに入り、確認済みのメモリは変更されません。
manage	読み取り／書き込み	1 件のエントリを操作します：list_pending、get_by_id、forget、restore、discard_pending。
get_context	読み取り	会話の開始に使う、最近の確認済みメモリの短い要約です。
say	書き込み	共有ボードに投稿し、ほかのエージェントに作業内容や引き継ぎ内容を伝えます。
board	読み取り	ボードを読み取ります。任意で、前回のカーソル以降に届いた内容だけに絞れます。

製品の本質に関わるため、次の 2 点は明確にしておきます。

• propose の成功は「キューに追加された」ことを意味し、「保存された」ことではありません。 人間が承認するまで、recall はその内容を返しません。
• manage に approve アクションはありません。 エージェントから確認済みのメモリに至る経路はありません。これは欠落ではなく、設計によるものです。

レスポンスの形式

tools/list は両方のエンジンで共通のインターフェイスであり、応答もそうあるべきです。どちらのエンジンが応答したかによって分岐する必要があるモデルは、いずれ誤った分岐をしてしまいます。そのため、board はアプリと同じ形式を、フィールドごとに返します。items、unread、count、cursor、reader を含みます。cursor は最新のカードの ID で、アプリが返すものと同じ種類の値です。

カーソルはエンジンの切り替えをまたいでポーリングに引き継がれるため、特に注意が必要です。auto では、ある呼び出しにはアプリが応答し、次の呼び出しにはローカルストアが応答することがあります。0.1.9 より前は、ローカルエンジンは浮動小数点数のエポックタイムスタンプを返し、アプリのカード ID を float() で読み取っていました。そのため、アプリから取得したカーソルを使うと、ボード全体を再読み込みすることになりましたが、そのことは通知されませんでした。逆方向では、浮動小数点数はカード ID に一致せず、アプリは最新の limit 件を同じく何も通知せずに返していました。

カーソルの解決に失敗する場合もあります。カードの有効期限が切れている場合（カードの有効期間はデフォルトで 24 時間）、または別のエンジンが発行した ID を使っている場合です。アプリの ID は CB…、こちらの ID は msg_… です。どちらのエンジンもそこから再開できないため、最新の範囲を返します。ただし、この場合は since_unknown も設定され、どちらの事象が起きたのかを示す note も返されます。unread はカーソル以降にある有効なカードの総数、count は応答に含まれるカードの数です。そのため、unread > count の場合は、待機中のカードをすべて取得できていないことを意味し、note にもその旨が記載されます。

エンジンごとに実際に保持するデータが異なるため、次の 3 つの形式は統一していません。

• recall エントリでは、ローカルストアの場合は保管庫を vault、アプリの場合は wh で示します。
• get_context は、ローカルでは単一のフラットな digest を返し、アプリでは倉庫ごとのバケット（倉庫名をキーとする context）を返します。
• roster エントリでは agent_id を共通で持ちます。ローカルではさらに messages と last_seen を持ちますが、アプリはそのレジストリカード（表示名、席、リース、現在のタスク）も追加します。SQLite ファイルにはそれを知る方法がありません。

エージェントの提案を承認する

エージェントは提案します。承認するのはあなたです。承認操作はターミナル内の、あなたが入力する必要のあるコマンドで行います。エージェントが呼び出せるツールには、意図的にしていません。

apiary-memory-cli list                 # what is waiting
apiary-memory-cli show <id>            # read one in full
apiary-memory-cli approve <id>         # confirm it, or --all
apiary-memory-cli reject <id>          # drop it for good
apiary-memory-cli search "deploy key"  # search confirmed memory
apiary-memory-cli forget <id>          # soft delete, reversible
apiary-memory-cli restore <id>         # undo forget
apiary-memory-cli stats                # counts and the database path
apiary-memory-cli export --out dump.json
apiary-memory-cli path

任意のコマンドで --db <path> を指定すると、別のデータベースを使用します。環境変数 HIVE_DB でも同じように指定できます。

メモリの保存場所

HIVE_DB で別の場所が指定されていない場合、~/.memory-hive/hive.db に保存されます。SQLite ファイルは 1 つだけです。バックアップするにはコピーし、最初からやり直すには削除してください。

ボードのメッセージも同じファイルに保存されるため、バックアップするものは常に 1 つだけです。カードには有効期限があります。ttl で別の値を指定しない限り 24 時間で、60 秒から 30 日の範囲に調整されます。これはアプリの動作と同じです。いつまでも増え続けるボードは、もはやボードではありません。

検索の仕組みと、検索でできないこと

中国語のテキストは、単一文字と重なり合う文字のバイグラムとしてインデックス化されます。ラテン文字のテキストは単語としてインデックス化されます。クエリの一致度を基にスコアを付け、さらに新しさに応じて調整します。10% の倍率で同点を解消しますが、関連性の順位を覆すほどではありません。

これはランキング機能であり、内容を理解する機能ではありません。

• スコアは相対値です。 0.8 は「このクエリでは 0.4 より一致度が高い」という意味であり、「80% の確信度」ではありません。クエリ間で比較することはできません。
• 意味に基づく想起はできません。 「お金」について尋ねても、「請求書」としか書かれていないエントリは見つかりません。関連語をカバーするには埋め込みモデルが必要ですが、このパッケージには依存関係がなく、そのように装うこともありません。
• ランキングは説明に記載されているとおりです。 ここでは tools/list に「単語と文字のバイグラム……埋め込みなし」と記載されており、このエンジンについてその説明は正しいものです。埋め込みの入力と同様、エンジンごとに対象を絞っています。これは、同じ質問に対するアプリの応答が異なるためです。
• 見つからなかった場合は、その旨を報告します。 一致するものがないとき、recall はそのことを伝え、承認待ちのエントリ数も示します。もっともらしい近似項目を返すことはありません。

設定

変数	デフォルト	用途
HIVE_MODE	auto	auto、local、または remote — 上の表を参照してください
HIVE_DB	~/.memory-hive/hive.db	ローカルデータベースの保存場所
HIVE_MCP_URL	http://127.0.0.1:8768/mcp	アプリのエンドポイント
HIVE_AGENT_ID	—	アプリのエージェント ID。アプリが処理する呼び出しでのみ使用します
HIVE_AGENT_TOKEN	—	アプリのアクセストークン。アプリが処理する呼び出しでのみ使用します

ローカルストアを使うために、HIVE_AGENT_ID と HIVE_AGENT_TOKEN は必要ありません。これらは環境から直接読み取られ、このパッケージによってディスクに書き込まれることはありません。

正直な制限事項

記憶ツールが実際以上のことを謳うのは、機能が少ないツールよりも悪いため、明記しています。

1. ローカルストアは暗号化されていません。 通常の SQLite です。ホームディレクトリを読み取れる人なら、誰でも内容を読めます。アプリのボルトが暗号化された選択肢であり、stats は、あとで自分で確認するまで気づかないということがないよう、"encrypted": false を報告します。
2. 上記のとおり、セマンティック検索には対応していません。
3. 一度に書き込めるのは 1 つだけです。 WAL モードでは、サーバー接続中でも CLI から確認できますが、これは個人用の記憶ファイルであり、複数ホスト向けのサービスではありません。ネットワーク共有上の 1 つのデータベースを複数のマシンから参照しないでください。
4. ボードは調整用であり、記憶用ではありません。 メッセージはエージェント間の引き継ぎ用であり、recall で検索することはできません。
5. アプリは macOS 専用です。 ローカルストアは macOS 専用ではなく、純粋な Python で実装されています。

トラブルシューティング

エントリが保留中なのに「このクエリに一致する確認済みの記憶がありません」と表示される。 これは正しい動作です。apiary-memory-cli list で確認し、その後 approve を実行してください。

HIVE_AGENT_ID に関するメッセージが表示され、呼び出しに失敗する。 アプリが応答し、認証情報を拒否しました。意図的にローカルストアへのフォールバックは行われていません。アプリにエージェントを登録して両方の変数を設定するか、ローカルファイルを使う場合は HIVE_MODE=local を設定してください。

「Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback」と表示される。 アプリのみを使うよう指定されていますが、アプリが起動していません。アプリを起動するか、HIVE_MODE=remote の指定を解除してください。

記憶が見つからない。 apiary-memory-cli stats を実行すると、データベースのパスが表示されます。HIVE_MODE が auto でアプリが起動している場合、アプリが応答しているため、設計上、ローカルファイルには変更が加えられていません。

開発

PYTHONPATH=src python -m unittest discover -s tests -v

テストスイートの実行に、起動中のアプリやネットワークは必要ありません。実際の応答が必要な場合は独自のフェイクバックエンドを立ち上げ、HIVE_DB を一時ファイルに設定するため、テストが実際の記憶データベースに触れることはありません。

レイアウト：

src/hive_mcp/store.py   the memory engine (SQLite, stdlib only)
src/hive_mcp/stdio.py   the MCP server: routing, envelopes, the app bridge
src/hive_mcp/cli.py     the human's half: review and confirm
src/hive_mcp/tools.json the tool surface snapshot for the offline path

ライセンス

MIT。記憶ファイルはあなたのものです。ここから外部に情報が送信されることはありません。