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，请切换到插件：
- 删除手动MCP服务器：
claude mcp remove twining - 安装插件：
/plugin marketplace add daveangulo/twining-mcp然后/plugin install twining@twining-marketplace - 清理：从
.claude/settings.json，删除.claude/agents/twining-aware.md如果存在，请从中删除缠绕部分CLAUDE.md（技能现在可以处理这个问题） - 保留：
.twining/目录（所有州保留） - 验证：
/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_assemble | 1号门： 在象征性的预算范围内为任务构建量身定制的上下文——决策、警告、移交 |
twining_record | 2号门： 记录你所做的一切和所做的任何选择——输入自然语言，输出结构化决策 |
twining_post | 在工作中分享发现、警告、需求或状态 |
twining_why | 在修改文件之前，检查哪些决策约束了文件 |
twining_housekeeping | 定期维护——归档、重复数据消除、表面过时决策（默认情况下为模拟运行）。可选的 staleness_review 和 merge_sweep 标记表面孤儿和合并后清理候选对象 |
twining_archive_stale | 将呼叫者确认的候选人ID存档，以防止过时或合并扫描审查。决策转移到 archived 地位；参赛作品被驳回。保存来源 |
twining_record 接受自然语言决策，如 "Chose Redis over Memcached — need persistence" 并自动将其解析为具有基本原理、被拒绝的替代方案和推断域的结构化记录。它还接受假设、约束、受影响的文件和依赖链——这是决策存储进行高保真上下文组装所需的一切。
扩展工具（随附 full_surface: true)
对于高级工作流——深度决策管理、图探索、多代理协调：
| 类别 | 工具 |
|---|---|
| 决策 | twining_decide, twining_search_decisions, twining_reconsider, twining_link_commit, twining_trace, twining_override, twining_promote, twining_commits |
| 黑板 | twining_read, twining_query, twining_recent, twining_dismiss |
| 上下文 | twining_summarize, twining_what_changed |
| 图 | twining_add_entity, twining_add_relation, twining_neighbors, twining_graph_query, twining_prune_graph |
| 协调 | twining_register, twining_agents, twining_discover, twining_delegate, twining_handoff, twining_acknowledge |
| 生命周期 | twining_verify, twining_status, twining_archive, twining_export |
启用 .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仓库设置>机密中配置）：
| 秘密 | 目的 |
|---|---|
NPM_TOKEN | npm访问令牌（粒度，范围为 twining-mcp) |
POSTHOG_API_KEY | PostHog摄取已发布包的密钥 |