Waggle Mcp

为人类和 AI Agent 提供项目记忆。
在不同对话间保留决策、上下文及其背后的原因。

安装 Waggle · 试用浏览器工作区 · 文档

---

保留上下文，而不只是对话

Waggle 是一个开源、本地优先的 AI Agent 记忆层。它将项目知识存储为图谱：你做出了什么决定、为什么重要、依赖什么，以及发生了哪些变化。下一次对话可以基于这些上下文继续，而不必从头开始。

通过 MCP 客户端使用 Waggle，在 Graph Studio 中查看和编辑记忆，或将可移植的记忆图谱带入浏览器工作区。

• 跨会话延续。 回忆项目决策、需求、偏好和未解决的问题，无需反复粘贴上下文。
• 了解推理过程。 探索关系、佐证、矛盾，以及决策背后的历史。
• 掌控修正内容。 在 WebMCP 工作区中，Agent 会提出更改；只有人类批准确切内容后，它才会成为权威信息。
• 随身携带记忆。 在支持的工作流间导入和导出 .abhi 文件，不必将图谱绑定到某个客户端。
• 从本地开始。 默认的 SQLite 存储位于你的计算机上。本地使用无需 Waggle 账户或外部数据库。

快速开始

Python 包需要 Python 3.11+ 和 pipx。在 macOS 上，可以使用 brew install pipx 安装 pipx；有关特定客户端的选项，请参阅安装指南。

pipx install waggle-mcp
pipx ensurepath

首次运行 pipx ensurepath 后，请重新启动终端，然后运行：

waggle-mcp setup --yes
waggle-mcp doctor

重新启动 MCP 客户端以加载 Waggle。安装程序会检测受支持的客户端并写入其配置；自动记忆功能使用客户端已安装的钩子、技能或项目说明。

要检查上下文延续效果，请让 Agent 记住一个项目决策，然后在同一项目中开启新会话，并询问做出了什么决定。请在不同会话中使用相同的项目标识符。

选择客户端

客户端	安装指南
Codex	安装 Waggle 插件或配置 MCP 服务
Claude Code	MCP 服务和自动记忆钩子
Claude Desktop	桌面扩展和手动配置
VS Code	Waggle 扩展和工作区设置
Cursor	连接本地 MCP 服务
Antigravity	客户端配置
其他 MCP 客户端	标准 MCP 配置
使用 Site 工具的 ChatGPT	使用浏览器工作区

对于接受 mcpServers 配置的客户端：

{
  "mcpServers": {
    "waggle": {
      "command": "waggle-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

如果找不到命令，请运行 pipx ensurepath 并重新打开终端。安装、启动和客户端连接问题，请参阅故障排除指南。

记忆的工作原理

Waggle 将持久的项目知识与模型的上下文窗口分开。 Agent 会在需要时检索相关记忆，并记录重要结果，供后续对话使用。

1. 记录： 记录决策、约束、偏好和支持性上下文。
2. 关联： 关联相关记忆，并保留矛盾和更新。
3. 回忆： 检索范围明确且附带证据和来源信息的上下文。
4. 延续： 在另一个会话或受支持的客户端中使用这些上下文。

核心 MCP 工作流使用 prime_context 加载项目上下文，使用 query_graph 检索相关历史，并使用 observe_conversation 记录持久结果。 build_context 会为特定任务整理出精简的上下文包。仅仅具备工具并不意味着 Agent 会自动使用记忆；必须通过钩子、技能或指令调用这些工具。

完整的 API 和检索设置请参阅工具参考和 配置参考。

Graph Studio

Graph Studio 让项目记忆可供查看和编辑。浏览节点和关系、添加或移除图谱内容、检查来源证据，并回顾记忆随时间的变化。

浏览器工作区提供聚焦于项目上下文、记忆、提案和活动的视图。Graph Studio 提供由服务端支持的记忆的图谱级视图；私有浏览器导入内容仍保留在工作区选项卡中。

打开 Graph Studio

WebMCP — 浏览器中的记忆

Waggle 工作区让人类和兼容的浏览器 Agent 使用同一份项目记忆。其 WebMCP 适配器通过 document.modelContext.registerTool 注册页面级 Site 工具。这与安装 Waggle 的 MCP 服务或配置远程 MCP 连接器是分开的。

连接并使用工作区

1. 在 ChatGPT 内置浏览器中打开工作区，并使用支持 Site 工具的模型和账户配置。
2. 在地址栏中检查 Site tools → Available site tools，确认五个 Waggle 工具均可用。使用记忆时，请保持此工作区选项卡打开。
3. 浏览示例项目，或选择 Load private .abhi 来使用自己的图谱。
4. 请求项目简介或回忆某个特定决策。在托管工作区中，使用 project_id: waggle-webmcp，包括导入自己的图谱后。
5. 如需更正记忆，请让 Agent 提议替换内容。在 Proposals 中查看提案，如有需要可进行编辑，然后批准准确的值。
6. 让 Agent 仅使用实际的提案 ID 应用已批准的提案。再次回忆该决策以确认结果，并查看其历史记录。

例如：

Call Waggle's get_project_brief with project_id "waggle-webmcp".
Use the returned memories to catch me up on this project.

如果 Site 工具不可用，请检查浏览器的权限和配置。 如果浏览器阻止了应用调用，你可以在已批准的提案上使用 Apply approved change，并自行确认操作。这会使用相同的审批和时效性检查，不会绕过浏览器防护措施。

浏览器工具

工具	功能
get_project_brief	返回项目目标、当前决策、约束、状态和未解决的问题。
recall_memory	查找与查询相关的当前权威记忆，并在可用时提供取代关系的来源信息。
propose_memory_change	创建待审核的更正，供人工审核，不会更改权威记忆。
apply_approved_memory_change	仅使用提案 ID 应用准确的已批准值。
load_abhi_for_session	将可移植图谱加载到此浏览器选项卡，并返回简介。

可供你审核的更正

flowchart LR
    A[Agent proposes a correction] --> B[Human reviews and approves]
    B --> C[Waggle checks approval and target version]
    C --> D[Approved value becomes authoritative]
    D --> E[Previous memory stays in history]

已批准的内容无法由应用更正的 Agent 修改。如果目标记忆自提案创建后发生了变化，提案会被标记为过期，而不会覆盖较新的信息。应用更正时会保留先前的记忆，并通过 updates 边将其链接到替换内容。

这些审批规则适用于 WebMCP 更正工作流。它们并不意味着每次直接编辑图谱或执行本地 MCP 操作都需要审批。

使用你自己的记忆

.abhi 文件是 Waggle 的可移植记忆图谱。浏览器导入器会读取现有记忆；它不会摄取源代码仓库来编造项目简介。

1. 在工作区中选择 Load private .abhi。
2. 选择一个未加密的 schema 2.x 文件，压缩后不超过 700 KiB，解压后不超过 4 MiB。
3. 确认出现 Private session graph 指示标记。简介、召回、提案和审批现在都会使用导入的副本。

导入会替换此标签页中的活动工作区；它不会与示例图谱合并、修改你的原始文件，也不会影响其他访客。

你也可以将文件附加到兼容的聊天中，并询问：

Use Waggle's load_abhi_for_session tool to load this .abhi file into
project "waggle-webmcp" for this session. Then call get_project_brief.

Agent 必须能够读取附件并以 base64 格式提供其字节。该工具不接受本地文件路径或下载 URL。如果聊天无法访问附件，请使用页面的文件选择器。

关于归档结构和支持的操作，请参阅可移植记忆格式。

你的数据与部署选项

使用 Waggle 的位置	记忆存储位置
本地 MCP 服务	你机器上的 SQLite，默认位于 ~/.waggle/waggle.db。
私有浏览器导入	此标签页的 sessionStorage；导入器不会将图谱上传到 Waggle 后端。
托管示例工作区	隔离的临时服务端示例项目；不是基于账户的云备份。
自托管远程 MCP 服务	你配置的 Neo4j 后端和基础设施。

浏览器生命周期。 私有导入内容在页面重新加载后仍会保留，浏览器会话恢复也可能保留这些内容。使用工作区的 Reset Demo 控件可明确清除私有副本并返回示例项目。仅关闭聊天对话并不能保证删除。导入器不会加密浏览器存储。

AI 服务。 在聊天中附加文件会将其分享给该聊天服务提供商。通过工具调用返回的记忆也会分享给发出请求的 AI 服务。本地存储并不意味着模型输入会留在你的设备上。

托管预览。 公共工作区用于体验浏览器功能，不适用于持久化生产存储。闲置时，免费托管服务可能暂停，唤醒可能需要时间，重启或重新部署时也可能丢失示例状态。打开该工作区不会连接到你的本地 Waggle 数据库。随附的 SQLite 预览配置会将临时状态存储在 /tmp 下，每个数据库最多允许 128 个会话，达到容量上限时会拒绝新会话，而不会逐出现有会话。

自托管。 浏览器预览的治理后端目前要求使用 SQLite。使用 Neo4j 托管远程 MCP 是另一套配置，并非浏览器工作流的直接替代方案。要进行远程部署，请配置 HTTPS、身份验证、持久化存储和备份。在公开服务器之前，请阅读生产部署指南、安全模型和安全加固清单。

开发

Waggle 使用 Python 实现记忆引擎和 MCP 服务，并使用 React/Vite 实现 Graph Studio 和浏览器工作区。

git clone https://github.com/Abhigyan-Shekhar/Waggle-mcp.git
cd Waggle-mcp
python -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

WAGGLE_MODEL=deterministic pytest -q
ruff check src/ tests/
ruff format --check src/ tests/

在 PowerShell 上，运行 pytest -q 前设置 $env:WAGGLE_MODEL="deterministic"。确定性嵌入可让测试在离线状态下运行；评估语义检索时，请使用常规嵌入模型。

对于前端更改：

npm ci --prefix apps/mcp/graph-ui
npm run test:unit --prefix apps/mcp/graph-ui
npm run build --prefix apps/mcp/graph-ui

文档和贡献

• 安装指南
• 工具参考
• 配置
• 便携式记忆格式
• 部署和安全
• 贡献
• 仓库概览
• 报告问题

许可证

Waggle 基于 Apache License 2.0 开源。