Context Fabric

Name: Context Fabric
Author: VIKAS9793

本地服务

github.com/VIKAS9793记忆与知识22 周前更新

代码仓库

关于 Context Fabric

Context Fabric 是面向多会话 AI 编码 Agent 项目的本地上下文同步 MCP 服务。它从 Git 提交捕获项目状态，检测上下文漂移，并按相关性和令牌预算生成简报。

主要功能

01Git 提交后自动捕获项目状态
02检测文件变化与上下文漂移
03按查询相关性检索组件
04按令牌预算筛选上下文
05生成结构化任务简报
06记录架构决策并检查本地健康状态

适用场景

01为新编码会话准备项目简报
02检查项目文档是否已过时
03控制注入 Agent 的上下文令牌量
04跨会话保留架构决策

MCP 相关

该 MCP 服务提供 cf_capture、cf_drift、cf_query、cf_health 和 cf_log_decision 等工具，为编码 Agent 捕获、查询和维护本地项目上下文。

#mcp-server #professional #context-drift #decision-log #cadre-engine

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "vikas9793-context-fabric": {
      "command": "npx",
      "args": [
        "-y",
        "context-fabric"
      ]
    }
  }
}

启动命令npx -y context-fabric

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmcontext-fabric1.2.2stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Context Fabric

当前稳定版本：v1.2.2。请参阅 CHANGELOG.md 了解发行说明。

官方注册表支持

Context Fabric 已配置为正式收录到 Model Context Protocol（MCP）注册表。

命名空间：io.github.VIKAS9793/context-fabric
元数据：server.json
分发方式：作为 npm 包发布，并附带官方 MCP 注册表元数据。

为 AI 编码 Agent 提供上下文同步层。确保项目连续性，消除 Agent 记忆偏移，并在任何编码会话中自动管理令牌预算。

Context Fabric 是一个 MCP 服务，可在每次 git 提交时自动捕获项目状态，检测已存储的上下文是否与代码库实际情况发生偏移，并向 AI Agent 提供结构化且符合令牌预算的简报——无需开发者采取任何操作。

问题

使用 AI 编码 Agent 的开发者，会手动构建和维护文档系统、会话交接流程和上下文工作流，以弥补原生项目连续性工具的缺失。这些变通方案有一个共同点：提交代码后就会过时，而且没有任何机制能检测到这一点。

问题不在于 AI 会遗忘，而在于上下文偏移——代码发生更改后，已存储的上下文会变得不准确，而 AI Agent 却会自信地基于这些错误上下文继续工作。

Context Fabric 是从根本上解决这一问题的基础设施层。

CADRE — 上下文感知偏移解决引擎

Context Fabric 由 CADRE 驱动，这是一个由五个引擎组成的内部架构。每个引擎都针对真实开发工作流中观察到的一种特定且有据可查的失效模式。

CADRE 是什么。 CADRE 是开发者目前自行构建的各种手动上下文管理系统的自动化替代方案。它位于 git 事件流与 AI Agent 之间，负责决定要捕获哪些上下文、何时发生偏移、哪些部分与当前查询相关、它们消耗多少令牌，以及如何以结构化且可靠的方式交付。

CADRE 面向谁。 面向构建多会话 AI 辅助软件项目的开发者，尤其是目前需要花时间做以下任一工作的开发者：在提交后更新 Markdown 文件、创建会话结束摘要、维护 CLAUDE.md 或 AGENTS.md 文件、为项目上下文构建 RAG 流水线，或在每项任务开始前手动决定要加载哪些文档。

五大引擎

E1 — WATCHER

在运行 context-fabric init 时安装 git 提交后钩子。每次提交时自动触发。读取已提交的 Git blob，而不是可变的工作区，计算 SHA256 指纹，提取导出符号，计算令牌估算值，并将所有内容写入本地 SQLite 存储。设置完成后，开发者无需再做任何操作。

替代：每次提交都编写 Markdown 的工作流、5 步会话流程，以及会话开始前用于提取结构化项目信息的 AI 访谈工作流。

E2 — ANCHOR

每次调用 cf_query 时，都会将已存储的 SHA256 哈希与每个受跟踪文件的当前状态进行比较。返回 DriftReport，其中包含 0–100 的漂移分数和严重程度分类：LOW（低于 10%）、MED（10–30%）、HIGH（高于 30%）。过时文件会按路径和哈希差异标出。

替代：手动检查文档是否与实际情况一致，以及 ETH Zurich 的研究（arXiv:2602.11988）证明会降低 AI 编码性能、却未被发现的 AGENTS.md 过时问题。

E3 — ROUTER

使用 cf_query 中的查询文本，对已存储的组件索引运行 SQLite FTS5 BM25。按相关性对组件进行排序并返回。路径匹配的权重是导出符号匹配的 2 倍，因为文件路径承载着有关代码库组织结构的含义。当查询未产生任何 MATCH 结果时，回退到按最近更新时间排序。

替代：针对每项任务手动选择要包含哪些文档，以及项目将知识拆分到多个文件后出现的模块化上下文选择问题。

E4 — GOVERNOR

使用贪心选择，对 E3 按相关性排序的结果应用可配置的令牌预算上限。默认值：模型上下文窗口的 8%，剩余 92% 用于对话和代码。超出预算的组件会被跳过，以便将剩余预算用于后续排名的匹配项。E1 预先计算了令牌估算值，因此预算选择时无需额外读取文件。

替代：手动管理令牌，以及为了避免重启时恢复上下文的成本而无限期保持会话运行的做法。

E5 — WEAVER

根据 E3 和 E4 的输出，生成结构化 Markdown 简报。包含以下部分：项目状态、架构、架构决策、预算摘要。当 E2 的严重程度为 MED 或 HIGH 时，会在所有其他内容之前添加漂移警告部分，让 AI 在阅读上下文前了解其可靠性。

替代：永不更新的静态 AGENTS.md 简报，以及开发者每次开始会话时手动准备简报的做法。

数据流

git commit
    |
    v
E1 WATCHER --- SHA256 fingerprint --- SQLite upsert --- FTS5 index update
                                                              |
                                                      cf_query("...")
                                                              |
                                                              v
                                        E2 ANCHOR --- drift check --- DriftReport
                                                              |
                                                              v
                                        E3 ROUTER --- FTS5 BM25 --- ranked component list
                                                              |
                                                              v
                                        E4 GOVERNOR --- greedy selection --- budget-capped set
                                                              |
                                                              v
                                        E5 WEAVER --- briefing composition --- MCP response

快速开始

npx context-fabric init

初始化 SQLite 存储，安装 git 提交后钩子，将稳定的本地运行时暂存到 .context-fabric/runtime，并执行初始捕获。将 MCP 服务连接到你的工具后，从下一次提交开始即可交付上下文。

安装与设置

初始化项目：前往任意由 git 管理的仓库并运行：
```
npx context-fabric init
```

配置 AI 环境（Cursor/VS Code/Windsurf）：将以下内容添加到 MCP 配置文件中。

Windows 用户（重要）：

{
  "mcpServers": {
    "context-fabric": {
      "command": "cmd",
      "args": ["/c", "npx", "context-fabric"]
    }
  }
}

Mac / Linux 用户：

{
  "mcpServers": {
    "context-fabric": {
      "command": "npx",
      "args": ["-y", "context-fabric"]
    }
  }
}

健康检查与修复

验证本地安装或从损坏的钩子/运行时状态中恢复时，请使用健康检查命令。

npx context-fabric doctor
npx context-fabric doctor --repair

doctor 会报告架构版本、搜索索引版本、数据库完整性、降级模式、待处理和失败的捕获，以及钩子运行时是否就绪。doctor --repair 会刷新本地运行时包、重新安装稳定的钩子包装器、验证 .gitignore，并在数据库健康时重建搜索索引。

故障排除

`spawn npx ENOENT` 错误

这通常意味着 npx 不在 IDE 的系统继承路径中。

修复方法：使用 node 和 context-fabric 二进制文件的绝对路径。
使用 where node（Windows）或 which node（Mac/Linux）查找路径。

NVM/FNM 用户示例：

"command": "/Users/name/.nvm/versions/node/v22.14.0/bin/node",
"args": ["/Users/name/.nvm/versions/node/v22.14.0/bin/context-fabric"]

WSL 用户

如果你在 Windows 上运行 VS Code，但代码位于 WSL 中，必须在 WSL 终端内运行 init，并在配置中使用 node 的 WSL 绝对路径。

项目路径中的空格

在 Windows 上，项目路径中的空格（例如 C:\My Projects\app）可能会导致 npx 启动失败。如果服务启动失败，可以考虑将项目移至不含空格的路径。

反馈与问题报告

如果出现问题，请运行：

npx context-fabric doctor

npx context-fabric diag 仍可作为兼容别名使用。

常见问题

Context Fabric 会将我的代码发送到服务端吗？ 不会。它仅在本地运行，不会为捕获、检索或漂移分析发起外部网络请求。

它会为未提交的更改编制索引吗？ 不会。捕获的状态基于已提交的 Git 对象。漂移检查会检测未提交的更改，但在你提交并捕获之前，不会将这些更改编入索引作为新的事实来源。

它能替代 AGENTS.md、CLAUDE.md 或人工编写的文档吗？ 它可以减少对手动编写会话交接文档的需求，但不能替代产品规格、入门指南或面向利益相关方的文档。

它会在本地写入哪些文件？ 它会在 .context-fabric/ 下写入数据库和运行时包，并安装 .git/hooks/post-commit，以便自动进行捕获。

什么时候不应该使用它？ 如果你需要云同步、跨仓库搜索、对实现代码主体进行完整语义索引，或通过 MCP 工具修改项目文件，请勿使用 Context Fabric。

如何修复损坏的安装？ 先运行 npx context-fabric doctor。如果需要修复钩子运行时或本地状态，请运行 npx context-fabric doctor --repair。

完整常见问题：docs/FAQ.md

MCP 工具

工具	引擎	用途
`cf_capture`	E1	在 git 提交之外手动捕获上下文
`cf_drift`	E2	独立漂移检查——返回严重程度和过时文件数量
`cf_query`	E2 + E3 + E4 + E5	为当前任务提供完整的上下文简报
`cf_health`	本地健康状态	报告数据库、捕获、钩子和搜索索引的健康状态
`cf_log_decision`	存储	在不同会话间持久保存架构决策

自 1.1.0 起，所有工具都会公开 MCP annotations（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）。cf_capture、cf_drift、cf_health 和 cf_log_decision 还会在文本输出之外返回 structuredContent；cf_query 则有意不返回，因为它的输出是供注入 Agent 上下文窗口的散文，而非数据结构。请注意，cf_query 不是只读的——如果 HEAD 尚未编入索引，它可能会在内部触发捕获。

技术栈

层	软件包	版本
MCP 协议	`@modelcontextprotocol/sdk`	`1.29.0`
存储与搜索	`better-sqlite3` + FTS5	`12.8.0`
架构验证	`zod`	`^4.3.6`
语言	TypeScript	`5.5+`
运行时	Node.js	`>=22.0.0 <25.0.0`
传输	stdio（阶段 1）	MCP SDK 内置

安全

访问类型	范围
文件系统读取	仅限项目根目录——拒绝路径遍历
文件系统写入	`.context-fabric/cf.db`、`.context-fabric/runtime/**`、`.context-fabric/bin/post-commit` 和 `.git/hooks/post-commit`
网络	无——不建立任何外部连接，也不收集遥测数据
项目文件写入	无——工具调用不会写入项目文件

有关漏洞披露流程，请参阅 SECURITY.md。

要求

Node.js >=22.0.0 且 <25.0.0
一个 git 仓库
任意兼容 MCP 的 AI 编码工具

贡献

提交拉取请求前，请阅读 CONTRIBUTING.md。

项目文档

👥 项目团队

VIKAS SAHANI — 产品负责人 / HITL / Agent 编排器
Antigravity — AI Agent / 代码架构师

🔬 研究与数据免责声明

本项目是针对 AI 原生开发工作流和上下文感知漂移解决方案的持续研究的一部分。

公开数据：公开会话期间生成的片段、日志或指标可能会用于研究和验证。
隐私：除非明确共享，否则不会在本地 .context-fabric 目录之外存储任何个人数据或专有代码库逻辑。

许可证

MIT — 请参阅 LICENSE。

由 VIKAS SAHANI 构建。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Context Fabric

关于 Context Fabric

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Context Fabric

官方注册表支持

问题

CADRE — 上下文感知偏移解决引擎

五大引擎

数据流

快速开始

安装与设置

健康检查与修复

故障排除

spawn npx ENOENT 错误

WSL 用户

项目路径中的空格

反馈与问题报告

常见问题

MCP 工具

技术栈

安全

要求

贡献

项目文档

👥 项目团队

🔬 研究与数据免责声明

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

`spawn npx ENOENT` 错误