butler-memory-mcp

给你的 AI agent 一份真正属于你的长期记忆。 一个 MCP 服务器，把你明确要求 记住的事实、偏好和项目上下文写入你自己的 PostgreSQL——每次写入带修订历史 与审计证据，检索自动按敏感度过滤。模型不能静默写入；推断出的东西只会变成 等你决定的候选。接任何 MCP 客户端即用。

仓库简介

Layered long-term memory for AI agents as an MCP server — PostgreSQL-backed, versioned, audited. Agents remember only what you explicitly asked.

Butler 分层记忆的 MCP 桥：把 ai-butler-framework 的 MemoryService / LayeredMemoryService 以标准 MCP 工具暴露给任何 MCP 客户端 （DSH、Claude Code、Codex 等），同时提供一个仅限 loopback 的 HTTP API 供 DSH Web 面板（dsh-butler-memory）读取。

DSH agent ──(MCP stdio)──► ai-butler-memory-mcp ──► MemoryService ──► PostgreSQL
DSH web 面板 ──(HTTP 127.0.0.1:8771)──► 同一进程、同一 principal

自包含分发（vendored）

本包运行时零依赖 ai-butler-framework：所需的记忆领域代码 （MemoryService/LayeredMemoryService/ORM 模型/数据库与配置辅助）以 vendoring 方式内置于 ai_butler_memory_mcp/vendored/，归属校验、敏感度上限、 revision 乐观锁、审计与证据同事务等语义与上游逐字一致。上游文件清单、 行号区间与漂移检查见 VENDORED.md（scripts/check-vendored.py）。

Schema 迁移仍由 ai-butler-framework 的部署负责（ai-butler-db upgrade）； 本包只连接已有数据库，不创建、不修改 schema。

安装

从 PyPI（发布后推荐）

pip install butler-memory-mcp

本地开发（源码 checkout）

cd butler-memory-mcp && python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

配置

复制 .env.example 为 .env，填三个值：

1. AI_BUTLER_DATABASE_URL — 与框架共用的 PostgreSQL；
2. AI_BUTLER_MCP_USER_ID — 记忆属主（ai-butler-admin bootstrap 输出）；
3. AI_BUTLER_MCP_DEVICE_ID — 桥作为该用户的一台持久设备：

.venv/bin/ai-butler-admin add-device \
  --user-id <USER_UUID> \
  --device-name dsh-agent --device-kind agent \
  --scope memory:read --scope memory:write

写操作只有在这台设备真实属于该用户时才会被框架接受——身份与审计不因 MCP 而放松。

运行

.venv/bin/ai-butler-memory-mcp                # stdio MCP（给 agent 用）
.venv/bin/ai-butler-memory-mcp --transport http --port 8771   # 面板 API

暴露的工具（DSH 中为 mcp__butler__memory_*）

当前边界（v0.1 刻意取舍）

• 无浏览器式强确认：MCP 写入依赖工具描述约束（"仅当用户明确要求"）+ 敏感度 封顶，不等于框架 Web 端的 L2 确认卡片。后续可接 DSH ask-user。
• 仅 loopback：HTTP 面板 API 拒绝非 loopback 绑定；stdio 模式不监听端口。
• 单用户单设备 principal：多用户映射属后续设计（见 PLAN.md）。
• 数据 durable 但备份/恢复尚未实现（框架 P9 未完成），发布说明中需如实标注。

测试

.venv/bin/pytest     # 离线协议测试；vendored 领域代码与上游逐字一致
.venv/bin/python scripts/check-vendored.py --upstream ../ai-butler-framework   # 漂移检查

License

Apache License 2.0，与上游 ai-butler-framework 一致。本项目不包含 任何专有模型或素材；发布衍生作品时请保留许可与署名要求。

相关项目

• ai-butler-framework — 记忆领域服务的上游实现方（owner/revision/audit 语义的权威来源；本包 vendoring 其记忆领域代码并做漂移检查）；
• dsh-butler-memory — DeepSeek Harness 接入组合包：agent 工具 + Web 记忆面板。