Polypack Memory

MCP クライアント向けの永続的で適応性のあるメモリ。

Polypack を永続的で適応性のあるメモリとして提供する MCP サーバーです。MCP 専用の ツールはこちらにあり、データベースは独立した依存関係として維持されます。

インストールと実行

最も簡単なインストール方法は PyPI からです。

python3 -m pip install 'polypack-mcp[polypack]'

1 つの MCP クライアントで使用する場合は、デフォルトの stdio サーバー設定を使います。Claude と Codex で同じ永続メモリを共有する場合は、一度インストールして、長時間実行する ユーザーサービスを作成します。

polypack-mcp setup --store ~/.local/share/polypack-mcp

これにより、http://127.0.0.1:8765/mcp/ でステートレスな Streamable HTTP サーバーが起動し、失敗時に 再起動して、クライアント設定の例を表示します。セットアップコマンドは systemd --user を使用します。systemd のないシステムでは、サーバーを直接起動してください。

polypack-mcp --transport streamable-http --port 8765 --store ~/.local/share/polypack-mcp

Streamable HTTP の共有モードでは、両方のクライアントに URL を設定します。共有永続ストアを 奪い合う 2 つのプロセスが起動するため、command と --store は設定しないでください。

Codex（~/.codex/config.toml）：

[mcp_servers.polypack]
  url = "http://127.0.0.1:8765/mcp/"

Claude Desktop：

{
  "mcpServers": {
    "polypack": { "url": "http://127.0.0.1:8765/mcp/" }
  }
}

Debian パッケージ

Debian パッケージは、システムレベルの polypack-mcp サービスを自動的にインストールして起動します。 専用の polypack ユーザーとして実行され、データを /var/lib/polypack-mcp に保存し、同じローカル Streamable HTTP エンドポイントを公開します。

sudo apt install ./polypack-mcp_<version>_amd64.deb

インストール後、Claude と Codex の接続先を http://127.0.0.1:8765/mcp/ に設定します。デフォルトのポートは /etc/default/polypack-mcp で変更でき、その後サービスを再起動します。サービスは次のコマンドで 管理できます。

sudo systemctl status polypack-mcp
sudo systemctl restart polypack-mcp

PyPI からのインストールは引き続きユーザー管理で、polypack-mcp setup を使用して ユーザーごとのサービスを作成します。

オプションのセマンティック検索

デフォルトのインストールでは、AI モデルをダウンロードせずに、Polypack のローカルグラフ、活性化、 および語彙検索を使用します。ローカルの Qwen セマンティック検索を有効にするには、次を実行します。

sudo polypack-mcp embeddings setup qwen3 --system --store /var/lib/polypack-mcp

管理対象の localhost ヘルパーを作成し、Qwen をストアの 埋め込みキャッシュに一度ダウンロードして、既存のメモリを再インデックスします。このモデルは Debian/RPM パッケージには含まれていません。

ヘルパーは Qwen3-Embedding-0.6B を bfloat16 で読み込み（読み込み後の常駐メモリは約 1GB、 fp32 では約 2.4GB）、15 分間操作がないとアンロードし、 次のリクエスト時に自動的に再読み込みします。ヘルパーに接続できる場合、 memory_recall の結果には scoreComponents に semantic エントリーが含まれ、 lexical および activation と並びます。3 つの値を合計すると、報告される score になります。 ヘルパーが停止しているかエラーになった場合、検索は自動的に lexical + activation のスコアリングにフォールバックします。次のコマンドで状態の確認や無効化ができます。

polypack-mcp embeddings status
sudo polypack-mcp embeddings disable --system --store /var/lib/polypack-mcp

PyPI のユーザーサービスでは、sudo --system を省略し、ユーザーストアを使用します。

polypack-mcp embeddings setup qwen3

APT リポジトリ

最新の Debian パッケージは、公開 APT リポジトリ https://imattau.github.io/polypack-mcp にも公開されています。リポジトリの 署名キーを使って設定した後、通常どおりインストールおよび更新できます。

curl -fsSL https://imattau.github.io/polypack-mcp/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/polypack-mcp.gpg
echo "deb [signed-by=/usr/share/keyrings/polypack-mcp.gpg] https://imattau.github.io/polypack-mcp stable main" \
  | sudo tee /etc/apt/sources.list.d/polypack-mcp.list
sudo apt update
sudo apt install polypack-mcp

リポジトリは、v*.*.* リリースタグごとに自動更新されます。メンテナー向けのセットアップ手順については、 docs/apt-repository.md を参照してください。

RPM パッケージ

RPM ベースのディストリビューションでは、公開 RPM リポジトリからインストールできます。

sudo rpm --import https://imattau.github.io/polypack-mcp/rpm/RPM-GPG-KEY-polypack-mcp
sudo tee /etc/yum.repos.d/polypack-mcp.repo >/dev/null <<'EOF'
[polypack-mcp]
name=Polypack MCP
baseurl=https://imattau.github.io/polypack-mcp/rpm/
enabled=1
gpgcheck=1
gpgkey=https://imattau.github.io/polypack-mcp/rpm/RPM-GPG-KEY-polypack-mcp
EOF
sudo dnf install polypack-mcp

対応する .rpm アセットは、 GitHub リリースにも添付されています。

sudo dnf install ./polypack-mcp-<version>-1.x86_64.rpm

RPM パッケージは、Debian パッケージと同じ systemd サービス、ストアの場所、localhost の Streamable HTTP エンドポイント、および Python 3.12 の要件を提供します。

手動で実行する

pip install -e '.[polypack]'
polypack-mcp --store ./polypack-data

サーバーは、用途を絞った17個のツールを公開します：memory_store、 memory_get、memory_update、memory_list_contexts、memory_delete、memory_recall、 memory_context、memory_feedback、memory_suppress、memory_supersede、 memory_consolidate、memory_link、memory_unlink、memory_thread、 memory_store_batch、memory_link_batch、graph_query。また、コンテキスト、 アクティブメモリ、スキーマ、統計、エージェントのワークフローガイダンスに関するリソースを polypack:// の下で公開します。

メモリクラスは entity、episodic、procedural、semantic です。プロジェクトやユーザーの設定は procedural メモリとして保存してください。preference は独立したメモリクラスではありません。

永続的な Polypack ストアを使用する場合、変更操作は直ちにチェックポイントを作成し、 サーバーはシャットダウン時にストアをフラッシュします。

検索ツールは {items, metadata} を返します。メタデータには、候補数と除外数、コンテキストの一致、 スコアの構成要素、フォールバックの動作、検索バージョン、選択統計が含まれます。memory_context は 推定トークン数（ceil(content characters / 4)、最小値は1）を token_budget として使用します。 残りの予算を超えるアイテムは返されません。0以下の予算は拒否されます。コンテキストはソフトな優先設定です。一致する メモリが優先され、スコープが設定されていないグローバルメモリはフォールバックとして使用される場合があります。 分離するには strict_context: true を指定してください。分離検索で結果が空の場合は、 reason: "no_context_match" と検索対象のコンテキストが報告されます。

memory_recall では、同じ呼び出しで関連するグラフメモリを任意でハイドレートできます：

{
  "query": "identity cache fix",
  "context": "cross-agent",
  "include_neighbors": true,
  "edge_types": ["RESPONDS_TO"],
  "depth": 2,
  "neighbor_limit": 3,
  "limit": 20,
  "token_budget": 4000
}

近傍のたどりはオプトイン方式で、上限が設定されています。limit は応答全体の上限、 neighbor_limit はハイドレートする近傍の上限です。追加の対象近傍が見つかった場合、メタデータで moreNeighborsAvailable が報告されます。近傍アイテムには距離と、接続する関係のメタデータが含まれます。 引き継ぎ、レビュー、修正など、以前のメモリに対応する内容には、デフォルトの RESPONDS_TO 関係を指定して memory_link を使用してください。グラフエッジが関係の正本です。 エッジによる裏付けのない従来の provenance.responds_to 値を見つけるには、 graph_query(operation="relationship_diagnostics") を使用してください。エージェント向けのワークフローについては、 polypack://help/workflow を参照してください。

フィードバックはアクティベーションへのフィードバックです。useful=true はメモリを強化し、 useful=false は検索に対する負のフィードバックを与えます。応答にはアクティベーションの変更前と変更後、 および学習済み重みが変化したかどうかが示されます。置換と統合では、 SUPERSEDES、SUPERSEDED_BY、CONSOLIDATED_FROM のグラフエッジが作成されます。

IDを正確に指定して検索するには memory_get を、変更可能なフィールド （コンテキスト、信頼度、プロベナンス、メタデータ）を更新するには memory_update を使用してください。 コンテンツを変更する場合は、履歴を維持できるよう memory_supersede を使用してください。関係を修正するには memory_unlink を、名前空間を調べるには memory_list_contexts を使用してください。memory_delete は 完全に削除する操作であり、confirm=true が必要です。また、任意でリビジョンチェックを指定できます。 履歴を保持することが有用な場合は、memory_suppress を優先してください。

永続的な Polypack ディレクトリを開くには --store を指定します。指定しない場合、サーバーは メモリ内のリファレンスバックエンドを使用します。これはスモークテストに便利です。 polypack エクストラには polypack-db>=3.3.1 が必要で、コンテキストの組み立てには、 ネイティブの ActivationEngine.working_memory セレクターを使用します。

開発

pip install -e '.[dev]'
pytest

テストスイートには、ツールの検出、メモリの保存と検索、リソースの読み取りを対象とする MCP クライアント／サーバープロトコルのスモークテストが含まれています。

ドキュメント

• はじめに
• 運用と設定
• トラブルシューティング