Polypack Memory

为 MCP 客户端提供持久、自适应的记忆。

一个将 Polypack 作为持久、自适应记忆提供的 MCP 服务。MCP 专用工具 位于此处；数据库仍是独立依赖项。

安装和运行

最简单的安装方式是通过 PyPI：

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

对于单个 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 配置两个客户端。不要使用 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 创建按用户运行的服务。

可选的语义检索

默认安装使用 Polypack 的本地图谱、激活和词法检索，不会下载 AI 模型。 要启用本地 Qwen 语义检索，请运行：

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

这会创建一个受管理的 localhost 助手，将 Qwen 下载一次到存储的 嵌入缓存中，并重新索引已有记忆。Debian/RPM 软件包不包含该模型。

该助手会以 bfloat16 加载 Qwen3-Embedding-0.6B（加载后常驻内存约 1GB， fp32 下约为 2.4GB），并在 15 分钟无活动后卸载， 下次收到请求时自动重新加载。只要该助手可用，memory_recall 结果的 scoreComponents 中就会包含 semantic 项，以及 lexical 和 activation——这三项相加即为报告的 score。 如果助手已停止或发生错误，召回会自动回退到词法 + 激活 评分。可通过以下命令检查或禁用它：

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 服务、存储位置、本地 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:// 发布上下文、活跃记忆、架构、统计信息和 Agent 工作流指南资源。

记忆类别包括 entity、episodic、procedural 和 semantic。将 项目或用户偏好存储为 procedural 记忆；preference 不是单独的记忆类别。

使用持久化 Polypack 存储时，变更操作会立即创建检查点，服务也会在关闭时刷新存储。

检索工具会返回 {items, metadata}。元数据包含候选项和排除项的数量、上下文匹配情况、评分组成部分、回退行为、检索版本和选择统计信息。memory_context 使用估算 token 数（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。邻居条目包含其距离和连接关系的元数据。对于处理较早记忆的交接、审查和修复，使用 memory_link，并采用默认的 RESPONDS_TO 关系。图边是关系的权威依据；使用 graph_query(operation="relationship_diagnostics") 查找没有图边支持的旧版 provenance.responds_to 值。有关面向 Agent 的工作流，请参阅 polypack://help/workflow。

反馈是激活反馈：useful=true 会强化记忆，useful=false 会提供负向检索反馈。响应会显示激活前后的值，以及学习到的权重是否发生变化。取代和整合操作会生成 SUPERSEDES、SUPERSEDED_BY 和 CONSOLIDATED_FROM 图边。

使用 memory_get 按 ID 精确查找，使用 memory_update 修改可变字段 （上下文、置信度、来源信息和元数据）。内容变更应使用 memory_supersede， 以保留历史记录。使用 memory_unlink 修正关系，使用 memory_list_contexts 发现命名空间。memory_delete 会永久删除记忆，必须传入 confirm=true，并可选择检查版本；如果保留历史记录有用，优先使用 memory_suppress。

传入 --store 可打开持久化 Polypack 目录。若不传入该参数，服务会使用内存中的参考后端，便于进行冒烟测试。 polypack 附加依赖要求 polypack-db>=3.3.1，并使用其原生的 ActivationEngine.working_memory 选择器来组装上下文。

开发

pip install -e '.[dev]'
pytest

测试套件包含 MCP 客户端/服务协议冒烟测试，涵盖工具发现、记忆存储、检索和资源读取。

文档

• 入门指南
• 运维与配置
• 故障排除