Twining MCP Server

问题所在

你花了两个小时与 Claude Code 一起做架构决策。你选择了 PostgreSQL 而不是 MongoDB。你确定使用 JWT 进行身份验证。你标记了支付模块中的竞态条件。然后会话结束了。

第二天你开始了一个新会话。Claude 对昨天发生的事情一无所知。决策消失了。警告消失了。理由消失了。你不得不重新解释一切——或者更糟的是，Claude 默默地与昨天的选择相矛盾。

当有多个智能体时，情况会更糟。智能体 A 决定使用 REST。智能体 B 为同一个服务选择了 gRPC。两者都不知道对方的存在。直到代码无法编译时你才会发现。

上下文窗口是短暂的。你的项目决策不应该是。

Twining 如何解决这个问题

Twining 是一个 MCP 服务器，为你的 AI 智能体提供持久的项目记忆。决策在上下文重置后依然存在。新会话开始时即已获知信息。多智能体工作保持协调。

# Install in 10 seconds
/plugin marketplace add daveangulo/twining-mcp
/plugin install twining@twining-marketplace

用自然语言记录你的所作所为：

twining_record({
  summary: "Added Redis caching to UserService",
  decisions: ["Chose Redis over Memcached — need persistence across restarts"],
  assumptions: ["Read-heavy workload (10:1 ratio)"],
  scope: "src/services/"
})

Twining 将你的决策解析为结构化记录——自动提取理由、被拒绝的替代方案和领域。一次工具调用，无需填写表单。

开始新会话。立即跟上进度：

twining_assemble({ task: "optimize the caching layer", scope: "src/services/" })

Twining 根据任务的相关性对每个决策、警告和发现进行评分，然后按优先级顺序填充令牌预算。你将获得所需的精确上下文——没有信息过载，无需重新解释。

询问事情为何如此：

twining_why({ scope: "src/auth/middleware.ts" })

返回任何文件的完整决策链：决定了什么、何时决定、为什么决定、拒绝了哪些替代方案，以及哪个提交实现了它。

为什么不直接使用 CLAUDE.md？

CLAUDE.md 是静态的。你写一次并手动更新。它不会在决策发生时捕获它们，不会跟踪理由或替代方案，不会检测智能体之间的冲突，也无法在令牌预算内选择性地组装上下文。

Twining 是动态的。每次 twining_decide 调用都会记录一个结构化决策。每次 twining_post 都会分享一个发现或警告。每次 twining_assemble 都会对相关性进行评分并提供当前任务所需的精确内容。.twining/ 目录是你项目的活的制度记忆。

为什么不使用编排器？

编排器（如智能体集群和分层协调器）通过分配任务来协调工作。Twining 通过共享状态来协调。区别很重要：

• 编排器将协调上下文保存在它们自己的上下文窗口中——这是一个单点故障，随着窗口填满，性能会下降

• Twining 的黑板将协调状态持久化在任何智能体的窗口之外，在上下文重置后依然存在，不会丢失信息

智能体通过读取黑板自行选择工作。没有中心瓶颈。没有会丢失上下文的中继。每个智能体都能直接看到其他所有智能体的决策和警告。

安装

插件安装（推荐）

# Add the marketplace (one-time)
/plugin marketplace add daveangulo/twining-mcp

# Install the plugin
/plugin install twining@twining-marketplace

包括 MCP 服务器、技能、生命周期钩子和预提交强制执行。两个门控：工作前使用 twining_assemble，提交前使用 twining_record——钩子会自动强制执行这两者。

团队自动安装

将此提交到你仓库的 .claude/settings.json 中，以便每个团队成员在克隆时都能获得 Twining：

{
  "extraKnownMarketplaces": {
    "twining-marketplace": {
      "source": {
        "source": "github",
        "repo": "daveangulo/twining-mcp"
      }
    }
  },
  "enabledPlugins": {
    "twining@twining-marketplace": true
  }
}

当团队成员信任存储库文件夹时，Claude Code 会自动安装市场和插件。

仅 MCP 安装

对于非 Claude-Code 客户端（Cursor、Windsurf 等）：

claude mcp add twining -- npx -y twining-mcp --project .

或者添加到 .mcp.json：

{
  "mcpServers": {
    "twining": {
      "command": "npx",
      "args": ["-y", "twining-mcp", "--project", "."]
    }
  }
}

MCP 服务器说明会自动包含在初始化响应中。

从手动安装升级

如果你之前手动配置过 Twining，请切换到插件：

1. 移除手动 MCP 服务器：claude mcp remove twining

2. 安装插件：/plugin marketplace add daveangulo/twining-mcp 然后 /plugin install twining@twining-marketplace

3. 清理：从 .claude/settings.json 中移除 Twining 钩子，如果存在则移除 .claude/agents/twining-aware.md，从 CLAUDE.md 中移除 Twining 部分（现在由技能处理）

4. 保留：.twining/ 目录（所有状态已保留）

5. 验证：/twining:status

充分利用它

该插件通过技能自动处理智能体指令。对于仅 MCP 安装路径，请将 Twining 指令添加到项目的 CLAUDE.md 中，以便智能体自动使用它——请参阅 docs/CLAUDE_TEMPLATE.md 获取可直接复制的模板。

仪表板

Web 仪表板会自动在 http://localhost:24282 启动——浏览决策、黑板条目、知识图谱和智能体状态。可通过 TWINING_DASHBOARD_PORT 配置。

内容概览

核心工具（始终可用）

这些是智能体在每次会话中使用的工具：

twining_record 接受诸如 "Chose Redis over Memcached — need persistence" 之类的自然语言决策，并自动将其解析为带有理由、被拒绝的替代方案和推断领域的结构化记录。它还接受假设、约束、受影响的文件和依赖链——决策存储库进行高保真上下文组装所需的一切。

扩展工具（full_surface: true 时可用）

用于高级工作流——深度决策管理、图谱探索、多智能体协调：

通过 .twining/config.yml 启用：

tools:
  full_surface: true

工作原理

所有状态都以纯文件形式存在于 .twining/ 中——黑板使用 JSONL，决策、图谱、智能体和交接使用 JSON。一切都可以使用 jq 查询、grep 搜索和 git diff。没有数据库。没有云。没有账户。

架构层：

• 存储 — 基于文件的存储，带有并发访问锁定

• 引擎 — 决策跟踪、黑板、图谱遍历、带令牌预算的上下文组装、智能体协调

• 嵌入 — 通过 @huggingface/transformers 实现的本地 all-MiniLM-L6-v2，延迟加载，带有关键字回退。服务器绝不会因为嵌入问题而无法启动。

• 仪表板 — 带有 cytoscape.js 图谱可视化和 vis-timeline 的只读 Web UI

• 工具 — 使用 Zod 验证的 MCP 工具定义，与工具表面 1:1 映射

请参阅 TWINING-DESIGN-SPEC.md 获取完整规范。

常见问题解答

Twining 会拖慢 Claude Code 吗？ 不会。它是一个本地 MCP 服务器——工具调用是本地文件读写。语义搜索在首次使用时延迟加载。

我可以将其与 Cursor、Windsurf 或其他 MCP 客户端一起使用吗？ 可以。Twining 是一个标准的 MCP 服务器。任何 MCP 主机都可以连接到它。

我的数据去哪了？ 所有协调状态都本地存储在 .twining/ 中。工具调用指标本地存储在 .twining/metrics.jsonl（已 gitignore）中。可选的匿名遥测可以启用——请参阅下方的 分析。

Twining 是智能体编排器吗？ 不是。它是一个协调状态层。它捕获智能体决定了什么以及为什么，并将这些知识提供给未来的智能体。将其与编排器、智能体团队或独立会话一起使用。

分析

Twining 包含一个三层分析系统，帮助你了解它提供的价值。

洞察仪表板选项卡

Web 仪表板包含一个 洞察 选项卡，显示：

• 价值指标 — 盲目决策预防率、警告确认、通过 tested_by 图谱关系的测试覆盖率、提交可追溯性、决策生命周期、知识图谱统计和智能体协调指标

• 工具使用情况 — 调用次数、错误率、每个工具的平均/P95 延迟

• 错误细分 — 按工具和错误代码分组的错误

所有价值指标均根据现有的 .twining/ 数据计算得出——无需收集新数据。

工具调用指标

每个 MCP 工具调用都会自动进行计时和成功/错误跟踪。指标本地存储在 .twining/metrics.jsonl 中（已 gitignore——操作数据，非架构数据）。

要禁用本地指标收集，请在 .twining/config.yml 中设置：

analytics:
  metrics:
    enabled: false

选择性遥测

匿名聚合使用数据可以选择性地发送到 PostHog，以帮助改进 Twining。默认禁用。 要启用，请添加到 .twining/config.yml：

analytics:
  telemetry:
    enabled: true

就是这样——PostHog 项目密钥已内置在源代码中。如果你运行自己的 PostHog 实例，可以使用 posthog_api_key 和 posthog_host 进行覆盖。

发送的内容： 工具名称、调用持续时间、成功/失败布尔值、服务器版本、操作系统、架构。

从不发送的内容： 文件路径、决策内容、智能体名称、错误消息、工具参数、环境变量。

隐私保护：

• DO_NOT_TRACK=1 环境变量始终覆盖配置

• CI=true 自动禁用遥测

• 身份是主机名 + 项目根目录的 SHA-256 哈希（从不使用原始路径）

• 网络故障静默处理——无重试

• posthog-node 是一个可选依赖项——如果未安装，则优雅地无操作

开发

npm install       # Install dependencies
npm run build     # Build
npm test          # Run tests (800+ tests)
npm run test:watch

需要 Node.js >= 18。

CI/CD

两个 GitHub Actions 工作流自动化构建验证和发布：

CI (.github/workflows/ci.yml) — 在每次 PR 和推送到 main 时运行：

• 在 Node 18、20 和 22 上构建和测试

• 当新推送到达同一分支时取消正在进行的运行

发布 (.github/workflows/publish.yml) — 在 v* 标签推送时运行：

• 使用内置的 POSTHOG_API_KEY 为已发布的包进行构建

• 运行完整的测试套件作为深度防御

• 使用 --provenance 发布到 npm 以进行供应链证明

• 创建带有自动生成发行说明的 GitHub Release

• 支持通过带有试运行选项的 workflow_dispatch 手动触发

发布新版本：

npm version patch   # or minor, major
git push && git push --tags

所需密钥（在 GitHub 仓库设置 > Secrets 中配置）：

许可证

MIT