polymnemo

polymnemo

通过 MCP，让任何大模型共享长期记忆。

将 Claude Desktop、支持 MCP 的 IDE 或任何 MCP 客户端连接到同一个 polymnemo 端点，它们就能共享相同的记忆——这些记忆存储在你自己的 Postgres 中。使用一个助手存储事实，再从另一个助手中回忆；保存完整会话并重新加载；甚至还能附加文件、图像或视频。嵌入在本地运行（无需嵌入 API 密钥），服务不会调用生成式大模型。

状态： 正在积极开发中。语义记忆与 pgvector 存储、会话保存与重新加载，以及多媒体记忆均已可用；可通过 Terraform 部署到 Azure Container Apps（或 Cloud Run）。 Wiki · Issues

功能

• 🔗 跨大模型共享 — 将任何 MCP 客户端连接到同一个端点，即可共享相同的记忆。
• 🧠 语义回忆 — 在 Postgres + pgvector 上进行向量搜索，而非关键词匹配。
• 💬 会话 — 保存完整对话记录并原样重新加载，也可以在其中进行回忆。
• 🖼️ 多媒体 — 附加文件、图像或视频；字节存入对象存储，仅将可搜索的描述用于嵌入。
• 🔒 本地且私密 — 嵌入在本地运行（ONNX）：无需嵌入 API 密钥，也绝不会调用生成式大模型。
• 👥 命名空间 — “创建时即共享”的集合可供所有人读取，与仅限所有者访问的集合相对；写入始终限定于所有者。
• 🧩 可插拔层 — 存储、嵌入器、身份验证、检索器、二进制对象存储和速率限制器均可替换，且都遵循 Protocol。
• ☁️ 多云部署 — 使用同一 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")]

请求携带一个 bearer key（用于解析出 user_id）；工具通过速率限制关卡后，会将请求交给 MemoryService，由它对文本分块并生成嵌入向量，再将向量存储在 pgvector 中——大型文件会通过预签名 URL 存入对象存储，只有可搜索的描述会生成嵌入向量。

每一层都是 typing.Protocol，并由组合根（context.py）连接，因此你可以替换实现，而无需改动工具：

层	默认实现	可替换为
存储	PostgresStore（pgvector）	InMemoryStore（开发/测试）
嵌入器	fastembed（本地 ONNX）	StubEmbedder（离线）
身份验证	GitHub OAuth + API 令牌	静态 bearer key（开发用）
检索器	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 和至少一个 API key：

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

每个 key 都会将一个 bearer token 映射到一个 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 服务的客户端，都需要以下两项：

• 端点： 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" }
    }
  }
}

也可以通过 inspector 验证：

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 登录，或提供 bearer token。无论哪种方式，请求都会解析为一个 user_id，写入操作按所有者隔离（你只能编辑或删除自己的记忆）。
• 无头客户端 —— CI、cron 作业和服务端 Agent 无法完成浏览器登录，因此会改用 API token。在 <server>/tokens 使用 GitHub 登录，即可创建、列出和撤销这些 token；新 token 只会显示一次，并且只以 SHA-256 哈希形式存储。它们刻意不设为 MCP 工具——机密绝不能通过大模型通道传输。
• 命名空间 —— 记忆存放在命名空间中。共享命名空间（默认值为 shared）对所有人可读（“创建即共享”）；其他所有命名空间都仅对其所有者私有。会话和媒体默认使用私有命名空间。
• 分块 —— 写入时，较长的内容会被拆分成多个块（每块对应一个向量），因此 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 extra）。

完整参数和返回结构请参阅专门的 MCP 工具参考 （即将推出）。关于键、命名空间和分块的工作方式，请参阅概念。

配置

POLYMNEMO_* 环境变量（或 .env）——完整列表见 .env.example。必需配置如下：

变量	默认值	用途
POLYMNEMO_DATABASE_URL	（未设置）	Postgres+pgvector DSN。生产环境必需；未设置时使用内存模式（开发/测试）。
POLYMNEMO_API_KEYS	（空）	"key1:alice,key2:bob" — Bearer 身份验证必需。
POLYMNEMO_SHARED_NAMESPACES	shared	所有用户均可读取的命名空间。
POLYMNEMO_HOST / POLYMNEMO_PORT / POLYMNEMO_MCP_PATH	127.0.0.1 / 8000 / /mcp	传输配置。
POLYMNEMO_RATELIMIT_ENABLED / _PER_MIN	false / 600	可选的全局速率限制（每分钟操作数）。
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）会运行 lint 和测试套件、生成覆盖率，并在每次运行的摘要中发布通过/失败/覆盖率表格。

部署

polymnemo 无状态（所有状态都存储在 Neon 和对象存储中），因此可在支持缩容至零的 Azure Container Apps（主要方案）或 Google Cloud Run 上运行。所有内容均通过 Terraform 管理，位于 deploy/terraform/：共享的 neon/（Postgres）和 r2/（媒体存储桶）根模块管理持久化状态，计算根模块则部署读取两者的服务——这样记忆和媒体都能跨云共享。

Azure 部署路径可通过 CI 一键完成：设置 GitHub secrets （scripts/setup-github-secrets.sh），初始化状态后端 （scripts/bootstrap-tfstate-azure.sh），然后运行 deploy (azure) 工作流 （neon → schema → r2 → build → app）。GCP 用作手动故障转移方案。完整操作指南见 docs/deploy.md。

许可证

MIT — 参见 LICENSE。