Twining MCP Server

Your AI agents forget everything. Twining remembers.

Persistent project memory for Claude Code and other MCP clients.

______________________________________________________________________

问题

你花了两个小时与Claude Code一起做出架构决策。你选择PostgreSQL而不是MongoDB。您选择JWT进行身份验证。您可以在支付模块中标记比赛条件。然后会议结束。

明天你开始一个新的会议。克劳德不知道发生了什么事。决定已经过去了。警告已经消失了。理由不复存在。你重新解释了一切——或者更糟糕的是，克劳德默默地反驳了昨天的选择。

当有多个代理时，情况会变得更糟。代理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_decide 通话记录了一个结构化的决策。每 twining_post 分享一个发现或警告。每 twining_assemble 对相关性进行评分，并准确交付当前任务所需的内容。这 .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，删除 .claude/agents/twining-aware.md 如果存在，请从中删除缠绕部分 CLAUDE.md （技能现在可以处理这个问题）
4. 保留： .twining/ 目录（所有州保留）
5. 验证： /twining:status

充分利用它

该插件通过技能自动处理代理指令。对于仅MCP安装路径，请将Twining说明添加到项目的 CLAUDE.md 所以代理会自动使用它——请参阅 docs/CLAUDE_TEMPLATE.md 用于准备复制模板。

仪表板

web仪表板在以下位置自动启动 http://localhost:24282 --浏览决策、黑板条目、知识图和代理状态。可通过以下方式配置 TWINING_DASHBOARD_PORT.

Stats overview: blackboard entries, decisions, graph entities, and activity breakdown

Interactive knowledge graph: files, decisions, classes, and their relationships

里面是什么

核心工具（始终可用）

以下是代理在每个会话中使用的工具：

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

扩展工具（随附 full_surface: true)

对于高级工作流——深度决策管理、图探索、多代理协调：

启用 .twining/config.yml:

tools:
  full_surface: true

运作原理

所有州都住在 .twining/ 作为普通文件——JSONL用于黑板，JSON用于决策、图形、代理和切换。一切皆有可能 jq-可查询， grep-able和git diffable。没有数据库。没有云。没有账户。

架构层：

• 存储 --具有锁定功能的文件备份存储，用于并发访问
• 发动机 --决策跟踪、黑板、图遍历、带有令牌预算的上下文组装、代理协调
• 嵌入 --本地全MiniLM-L6-v2通过 @huggingface/transformers，延迟加载，带关键字回退。服务器永远不会因为嵌入问题而无法启动。
• 仪表板 --具有cytoscape.js图形可视化和vis时间线的只读web UI
• 工具 --使用Zod验证MCP刀具定义，将1:1映射到刀具表面

看 TWINING-设计规格.md 为了获得完整的规格。

常见问题

Twining会减慢Claude Code的速度吗？ 不是。这是一个本地MCP服务器——工具调用是本地文件读/写。语义搜索在首次使用时加载缓慢。

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

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

Twining是代理编排者吗？ 不，这是一个协调状态层。它捕获了代理的决定及其原因，并将这些知识提供给未来的代理。将其与编排者、代理团队或独立会话一起使用。

分析

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

洞察仪表板选项卡

web仪表板包括 洞察 选项卡显示：

• 价值指标 --盲决策预防率、警告确认、测试覆盖率 tested_by 图关系、提交可追溯性、决策生命周期、知识图统计和代理协调度量
• 工具使用 --每个工具的呼叫计数、错误率、平均/P95延迟
• 错误分解 --按工具和错误代码分组的错误

所有价值指标都是根据现有数据计算的 .twining/ 数据——不需要新的数据收集。

工具调用指标

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

要禁用本地指标收集，请在中设置 .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:

• 跨节点18、20和22进行构建和测试
• 当新推送到达同一分支时，取消正在进行的运行

发布 (.github/workflows/publish.yml)--继续 v* 标签推送：

• 构建与 POSTHOG_API_KEY 为已发布的包烘焙
• 运行完整的测试套件作为深度防御
• 发布到npm --provenance 供应链认证
• 使用自动生成的发行说明创建GitHub发行版
• 支持通过以下方式手动触发 workflow_dispatch 具有模拟运行选项

要发布新版本，请执行以下操作：

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

所需的秘密 （在GitHub仓库设置>机密中配置）：

许可证

麻省理工学院