Waggle-mcp

为什么选择 waggle-mcp？

大多数大语言模型在对话结束后就会忘记一切。 waggle-mcp 通过为您的 AI 提供一个持久化知识图谱解决了这个问题，AI 可以通过任何兼容 MCP 的客户端读取和写入该图谱。

Waggle 的核心优势在于基于结构化上下文的 Token 高效性：

关于检索的说明： Waggle 以牺牲部分原始召回覆盖率为代价，换取了极低的 Token 成本和更丰富的关系上下文。请参阅基准测试部分了解真实数据。

快速入门 — 30 秒

pip install waggle-mcp
waggle-mcp init

init 向导会自动检测您的 MCP 客户端，写入配置文件，并创建数据库目录——无需手动编辑 JSON。支持 Claude Desktop、Cursor、Codex 以及通用的 JSON 回退方案。

初始化后，重启您的 MCP 客户端，您的 AI 就拥有了持久化记忆。 无需云服务。无需 API 密钥。语义搜索完全在本地运行。

查看实际效果

以下是一位开发者每天使用 AI 时的实际前后对比：

会话 1 — 4 月 10 日

User:  Let's use PostgreSQL. MySQL replication has been painful.
Agent: [calls observe_conversation()]
       → stores decision node: "Chose PostgreSQL over MySQL"
       → stores reason node:   "MySQL replication painful"
       → links them with a depends_on edge

会话 2 — 4 月 12 日（全新的上下文窗口，无历史记录）

User:  What did we decide about the database?
Agent: [calls query_graph("database decision")]
       → retrieves the decision node + linked reason from April 10

       "You decided on PostgreSQL on April 10. The reason recorded was
        that MySQL replication had been painful."

会话 3 — 4 月 14 日

User:  Actually, let's reconsider — the team is more familiar with MySQL.
Agent: [calls store_node() + store_edge(new_node → old_node, "contradicts")]
       → conflict is flagged automatically; both positions are preserved in the graph

智能体无需明确指令即可记忆或检索——它根据对话调用了正确的工具，而图谱为其提供了正确的上下文。

工作原理

记忆不仅仅是被存储，它还经历了一个生命周期：

You talk to your AI
        │
        ▼
  observe_conversation()          ← AI drops the turn in; facts extracted via structured LLM (regex fallback)
        │
        ▼
  Graph nodes are created         ← "Chose PostgreSQL" becomes a decision node
  Edges are inferred              ← linked to the "database" entity node
        │
        ▼
  Future conversation starts
        │
        ▼
  query_graph("DB schema")        ← semantic search finds the node from 3 sessions ago
        │
        ▼
  AI answers with full context    ← "You decided on PostgreSQL on Apr 10, here's why…"

每个节点都携带使用 all-MiniLM-L6-v2 本地计算的语义嵌入——这是一个快速、轻量级的模型，完全在设备上运行，无需 API 密钥或网络调用。这意味着语义搜索可以离线工作，每次查询零成本，并保护您的数据隐私。

神奇工具：observe_conversation

这是您最常用的工具。 您不必手动存储事实——只需告诉智能体观察每一次对话轮次，它就会处理剩下的事情。

observe_conversation(user_message, assistant_response)

其底层逻辑：

1. 从对话双方提取原子事实

2. 使用语义相似度与现有节点进行去重

3. 在相关概念之间创建类型化边

4. 标记与现有存储信念的矛盾

无需指令。无需定义模式。只需观察。

在底层，每次调用都会运行一个 Pydantic 验证的 LLM 提取过程（带有正则表达式回退），从杂乱的对话中提取结构化事实。

示例： “我们用 PostgreSQL 吧，因为 MySQL 的复制太痛苦了。”

{
  "facts": [
    {
      "label": "PostgreSQL for generic events",
      "content": "Chose PostgreSQL over MySQL because MySQL replication is too painful.",
      "node_type": "decision",
      "confidence": 0.95,
      "tags": ["llm-extracted", "confidence:0.95"]
    }
  ]
}

任何 confidence < 0.5 或模式无效的提取都会被静默丢弃，以防止幻觉噪声。

记忆模型

节点类型 — 存储的内容：

边类型 — 节点如何连接：

relates_to · contradicts · depends_on · part_of · updates · derived_from · similar_to

MCP 工具

您的 AI 会直接调用这些工具——您无需手动使用它们。

性能与基准测试

以下所有数字均可使用 scripts/benchmark_extraction.py 中的工具，从 benchmarks/fixtures/ 中的固定装置中复现。保存的输出工件位于 tests/artifacts/。

一条命令即可生成以下所有表格（提取正则表达式基准、检索、去重以及对比 Token 效率的试点）：

PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend regex \
  --systems waggle rag_naive \
  --output tests/artifacts/benchmark_current.json

LLM 提取行（75%）需要使用本地 Ollama 实例单独运行——它不包含在 benchmark_current.json 中：

# Requires Ollama running locally with qwen2.5:7b pulled
PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend llm --ollama-model qwen2.5:7b --ollama-timeout-seconds 30

提取准确率

语料库：涵盖简单回忆、中断、反转、模糊陈述和冲突信号的 12 对对话（benchmarks/fixtures/extraction_cases.json）。

检索准确率

语料库：18 个节点，18 个查询 — 6 个简单（直接改写）和 12 个困难（对抗性：语义泛化、时间消歧、间接领域翻译、隐私框架）。来源：benchmarks/fixtures/retrieval_cases.json。

Token 效率对比朴素分块向量 RAG

上述检索准确率表衡量了 Waggle 独立的搜索质量。下方的对比使用了一个单独的多会话语料库，旨在测试其相对于分块向量基准的 Token 效率。

语料库：24 个多会话场景，涵盖 7 个任务系列的 66 个检索查询（benchmarks/fixtures/comparative_eval.json）。

Waggle 在此语料库上的每次检索使用的 Token 比朴素分块基准少约 4 倍。

Waggle 的 Hit@k (91%) 与精确支持 (74%) 之间的差距表明，图谱检索能找到正确的主题，但有时返回的支持细节不足——在 cross_scenario_synthesis 查询中最为明显（8/8 命中，1/8 精确）。改进上下文组装——特别是边遍历深度和多跳子图扩展——是下一步的跟踪任务。

这种权衡是诚实的：分块基准在此语料库上实现了 100% 的 Hit@k，因为在 top_k=5 时，每个事实都可以从其自身的会话块中检索到。Token 效率优势是真实且可复现的；检索优越性的主张需要一个分块覆盖无法弥补缺失关系上下文的语料库。语料库强化工作正在进行中。

当提取失败时

用户： “是的，我们就做我们刚才谈到的那件事吧。”

LLM 会对模糊输入分配低置信度（confidence < 0.5）；Waggle 会静默丢弃该提取，而不是存储猜测。管道在超时后不会静默回退到正则表达式——后端故障会作为明确的错误记录下来。

语料库：22 对节点 — 11 对真重复（同义词、改写、领域等价）和 11 对假朋友（相同技术类别，不同技术）。来源：benchmarks/fixtures/dedup_cases.json。

管道运行五个层级：

1. 第 0 层 — 实体键硬阻塞 — 如果两个节点在同一类别中命名了不同的技术（例如 postgresql vs mysql），则无条件阻止合并。

2. 第 0b 层 — 数值冲突防护 — 相同实体但关键数字不同（例如 jwt 15 分钟 vs 1 小时）→ 阻止。防止合并共享技术但在关键值上不同的不同事实。

3. 第 1 层 — 精确字符串匹配 — 归一化内容或标签相等。

4. 第 2 层 — 子字符串包含 — 一个句子是另一个句子的严格子集。

5. 第 3 层 — 语义相似度 — 通过 all-MiniLM-L6-v2 计算余弦相似度：

   • 同实体激进路径：如果两者引用了相同的实体令牌，则在余弦相似度 ≥ 0.60 时合并（捕获改写真重复，如“选择了 fastapi” / “我们选择 fastapi 是因为异步”）。

   • 类型感知阈值：decision/preference → 0.82；fact → 0.92；entity → 0.97

   • Jaccard 增强路径：词重叠 ≥ 0.35 且余弦相似度 ≥ (类型阈值 − 0.05)

   • 保守的全局回退

最佳测量结果：在阈值 0.82 时为 18/22 = 82%。所有阈值下的 fp=0 — 在任何测试阈值下都没有发生假朋友合并。

剩下的 4 个假阴性是纯改写对，没有可识别的实体锚点（“用户偏好深色模式” / “用户想要深色模式 UI”，“异步不可协商” / “并发且不阻塞”）。这些需要语义相似度微调或学习到的改写分类器来解决。

完整的阈值扫描和详细方法：tests/artifacts/README.md。

完整工件、方法论和 rag_tuned 对比：tests/artifacts/README.md
改进路线图（去重 → 上下文组装 → 语料库强化）：docs/evaluation-plan.md

时间查询 — 内置，而非外挂

大多数记忆系统能回答“关于 X 你知道什么？”——但无法回答你何时学到的，或者知识是如何随时间变化的。

waggle-mcp 会为每个节点添加时间戳，并理解时间相关的自然语言：