polymnemo

polymnemo

MCPを介して、あらゆるLLMで共有できる長期記憶です。

Claude Desktop、MCP対応IDE、または任意のMCPクライアントを1つのpolymnemo エンドポイントに接続すると、独自のPostgresに保存された同じ記憶を共有できます。あるアシスタントで事実を保存し、別のアシスタントから呼び出せます。セッション全体を保存して再読み込みすることも、ファイル、画像、動画を添付することもできます。埋め込み処理はローカルで実行されるため（埋め込みAPIキーは不要）、サーバーは生成LLMを呼び出しません。

ステータス： 開発中です。セマンティックメモリとpgvectorストア、セッションの保存と再読み込み、マルチメディアメモリが利用可能です。Terraformを使ってAzure Container Apps（またはCloud Run）にデプロイできます。 Wiki · Issues

機能

• 🔗 LLM間で共有 — 任意のMCPクライアントを1つのエンドポイントに接続すると、同じメモリを共有できます。
• 🧠 セマンティック検索 — キーワード照合ではなく、Postgres + pgvector上でベクトル検索を行います。
• 💬 セッション — トランスクリプト全体を保存してそのまま再読み込みするか、セッション全体から情報を呼び出せます。
• 🖼️ マルチメディア — ファイル、画像、動画を添付できます。バイトデータはオブジェクトストレージに保存し、検索可能な説明のみを埋め込みます。
• 🔒 ローカルかつプライベート — 埋め込み処理はローカル（ONNX）で実行されるため、埋め込みAPIキーは不要で、生成LLMを呼び出すこともありません。
• 👥 名前空間 — 誰でも読み取れる「作成時から共有」のコレクションと、所有者のみが利用できるコレクションを使い分けられます。書き込みは常に所有者ごとにスコープされます。
• 🧩 差し替え可能なレイヤー — ストア、埋め込み器、認証、検索機能、ブロブストア、レートリミッターはすべて差し替え可能なProtocolです。
• ☁️ マルチクラウドデプロイ — 1つのTerraformスタックでAzure Container AppsまたはCloud Runにデプロイでき、ゼロまでスケールできます。
• 🚦 レート制限 — オプションのグローバルトークンバケットに対応しています。

仕組み

flowchart LR
    Clients["MCP clients<br/>(Claude Desktop, IDEs, …)"] -->|"/mcp · Bearer key"| P["polymnemo<br/>(MCP server)"]
    P --> DB[("Postgres + pgvector<br/>text + pointers")]
    P -. "large files<br/>(presigned URLs)" .-> OS[("Object storage<br/>S3 / R2")]

リクエストにはベアラーキーが含まれ（これによって user_id が特定されます）、ツールはレート制限ゲートを通過した後、テキストをチャンクに分割して埋め込みを生成し、ベクトルを pgvector に保存する MemoryService に処理を委譲します。大きなファイルは署名付き URL を介してオブジェクトストレージに保存され、検索可能な説明のみが埋め込まれます。

すべてのレイヤーは typing.Protocol で定義され、コンポジションルート（context.py）によって接続されています。そのため、ツールに手を加えずに実装を切り替えられます。

レイヤー	デフォルト	切り替え先
ストア	PostgresStore（pgvector）	InMemoryStore（開発／テスト用）
埋め込み生成器	fastembed（ローカル ONNX）	StubEmbedder（オフライン用）
認証	GitHub OAuth + API トークン	静的ベアラーキー（開発用）
検索	VectorRetriever	独自のランキング機能
BlobStore	S3 / R2	無効
レートリミッター	グローバルなトークンバケット	無効

ping ツールは有効なレイヤーを返すため、実行中のサーバーがどのように接続されているか確認できます。

クイックスタート

Python 3.11 以降が必要です。

1. インストール

python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -e .                     # add ".[dev]" for the test + lint tooling

2. Postgres（pgvector）を用意する

永続ストアには Postgres + pgvector を使用します。ホスト型の選択肢として最も手軽なのは Neon です（プール済みの接続文字列を使用してください）。スキーマを一度だけ適用します。

psql "<your-connection-string>" -f scripts/schema.sql

3. 設定する

.env.example を .env にコピーし、データベース URL と少なくとも 1 つの API キーを設定します。

POLYMNEMO_DATABASE_URL=postgresql://user:pass@host/db?sslmode=require
POLYMNEMO_API_KEYS=sk-alice-secret:alice,sk-bob-secret:bob   # "key:user_id" pairs

各キーはベアラートークンを user_id に対応付けます。書き込みはそのユーザーに限定されます。

4. 実行する

polymnemo                            # Streamable HTTP at http://127.0.0.1:8000/mcp

または Docker を使用します。

docker build -t polymnemo .
docker run -e POLYMNEMO_DATABASE_URL="..." -e POLYMNEMO_API_KEYS="sk-alice-secret:alice" \
           -e PORT=8080 -p 8080:8080 polymnemo

5. MCP クライアントを接続する

カスタムヘッダーを使ったリモート（HTTP）MCP サーバーに対応するクライアントには、次の 2 つが必要です。

• エンドポイント： http://<host>:<port>/mcp
• ヘッダー： Authorization: Bearer <your-key>

mcpServers 設定を読み込むクライアントの場合：

{
  "mcpServers": {
    "polymnemo": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer sk-alice-secret" }
    }
  }
}

または、インスペクターで確認します。

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP · URL: http://127.0.0.1:8000/mcp
# Header:    Authorization: Bearer sk-alice-secret  → call ping / remember / recall

概念

• ユーザーとキー — GitHub でサインインするか、ベアラートークンを提示します。どちらの場合も、リクエストから user_id が特定され、書き込みは所有者に限定されます（自分のメモリーのみ編集または削除できます）。
• ヘッドレスクライアント — CI、cron ジョブ、サーバーサイドのエージェントはブラウザーでのサインインを完了できないため、代わりに API トークンを使用します。GitHub で <server>/tokens にサインインすると、トークンを作成、一覧表示、取り消しできます。新しいトークンは一度だけ表示され、SHA-256 ハッシュとしてのみ保存されます。意図的に MCP ツールにはしていません。シークレットが LLM の通信経路を通過してはならないためです。
• 名前空間 — メモリーは名前空間に保存されます。共有名前空間（デフォルトは shared）は全員が読み取れます（「最初から共有」）。それ以外はすべて所有者のみに公開されます。セッションとメディアの名前空間は、デフォルトで非公開です。
• チャンク分割 — 長いコンテンツは書き込み時にチャンクに分割され（各チャンクに 1 つのベクトルを割り当てます）、remember が複数の ID を返す場合があり、recall は最も近いチャンクを返します。
• シークレットのスキャン — 任意機能で、有効にしない限りオフです。スキャナーの設定を POLYMNEMO_RSP_CONFIG に指定してください（イメージには /app/plugins/rsp.toml が含まれています）。この変数を設定しない場合、すべての書き込みは何もしないガードを通過し、スキャンは行われません。有効にすると、メモリーのテキストは埋め込みや保存の前にスキャンされます。そのため、拒否された書き込みは後から削除されるのではなく、最初から書き込まれません。対象は remember、save_session、update、およびメディアメモリーの説明です。 アップロードされたファイルの内容はスキャンされず、送信されたまま保存されます。バイト列は署名付き URL を使ってオブジェクトストレージに直接送られ、このサーバーを通過しません。ファイルの説明はスキャンされますが、ファイル本体はスキャンされません。

ツール

polymnemo は、メモリの保存、検索、管理を行う MCP ツールを公開しています。

• メモリ — remember、recall、list_memories、get_memory、update、forget
• セッション — save_session、load_session
• メディア — create_upload、confirm_upload、get_download_url

さらに、ヘルスチェック用の ping と、コレクションを自動挿入する memory://{namespace} リソースもあります。メディアのバイトデータは、事前署名 URL を介してオブジェクトストレージに送られ、MCP チャネルを通ることはありません。埋め込まれるのは検索可能な説明のみです（blob エクストラが必要です）。

引数と戻り値の形式の全詳細は、専用の MCP ツールリファレンスに記載されています（近日公開）。キー、名前空間、チャンク化の仕組みについては、概念を参照してください。

設定

POLYMNEMO_* 環境変数（または .env）を使用します。全一覧は .env.example にあります。主な項目は次のとおりです。

変数	デフォルト	用途
POLYMNEMO_DATABASE_URL	(未設定)	Postgres+pgvector の DSN。本番環境では必須です。未設定の場合はインメモリ（開発／テスト用）になります。
POLYMNEMO_API_KEYS	(空)	"key1:alice,key2:bob" — ベアラー認証に必要です。
POLYMNEMO_SHARED_NAMESPACES	shared	すべてのユーザーが読み取り可能な名前空間です。
POLYMNEMO_HOST / POLYMNEMO_PORT / POLYMNEMO_MCP_PATH	127.0.0.1 / 8000 / /mcp	トランスポートです。
POLYMNEMO_RATELIMIT_ENABLED / _PER_MIN	false / 600	任意のグローバルレート制限（1 分あたりの操作数）です。
POLYMNEMO_BLOB_BACKEND (+ _BUCKET / _ENDPOINT_URL / _ACCESS_KEY_ID / _SECRET_ACCESS_KEY)	none	メディアメモリ用のオブジェクトストレージです。s3 は Cloudflare R2／S3 互換を意味します。
POLYMNEMO_RSP_CONFIG	(未設定)	スキャナー設定へのパスです。未設定の場合、スキャンは行われません。イメージには /app/plugins/rsp.toml が含まれています。

開発

pip install -e ".[dev]"
pytest                               # fast, offline (stub embedder, in-memory store)
ruff check . && ruff format --check .   # lint + format (enforced in CI)

TEST_DATABASE_URL が pgvector 対応の Postgres を指している場合、Postgres テストが実行されます。CI（.github/workflows/ci.yml）では、リントとカバレッジ付きのテストスイートを実行し、各実行のサマリーに合否とカバレッジの表を掲載します。

デプロイ

polymnemo はステートレス（すべての状態は Neon とオブジェクトストレージに保存）なので、スケール・トゥ・ゼロに対応する Azure Container Apps（主要環境）または Google Cloud Run で実行できます。すべて Terraform で管理します。deploy/terraform/ の共有 neon/（Postgres）と r2/（メディアバケット）のルートが永続状態を管理し、コンピューティングルートがその両方を読み込むサービスをデプロイします。そのため、メモリとメディアはクラウド間で共有されます。

Azure へのデプロイは、CI からワンクリックで実行できます。GitHub シークレット（scripts/setup-github-secrets.sh）を設定し、状態バックエンドを初期化してから（scripts/bootstrap-tfstate-azure.sh）、deploy (azure) ワークフロー（neon → schema → r2 → build → app）を実行します。GCP は手動でのフェイルオーバー先です。詳しい手順は docs/deploy.md を参照してください。

ライセンス

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