Ctx Engine

将文件系统作为AI的外部记忆，让AI像操作系统一样管理工作区状态

License: MIT

🎯 这是什么？

Context Engineering MCP 是一套工具集，实现了"文件系统作为外部记忆"的理念，帮助AI助手（如Claude、Cursor）更高效地管理上下文。

核心问题

AI编程时常遇到的困境：

• 🔴 上下文窗口有限：长输出（如npm install日志）占用大量token
• 🔴 多轮对话混乱：AI"忘记"之前的修改，反复犯错
• 🔴 缺乏项目认知：不了解代码库结构、团队规范、当前目标

解决方案

通过三层上下文体系 + 文件系统外部记忆：

┌─────────────────────────────────────────┐
│  Layer 1: 项目上下文                     │
│  - 代码库结构和现有实现                  │
│  - 架构设计文档 (ADR)                   │
│  来源: 代码仓库 + 项目文档               │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  Layer 2: 团队上下文                     │
│  - 编码规范和命名约定                    │
│  - API设计规范                          │
│  来源: .ai/skills/ 文档                 │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  Layer 3: 技术栈上下文                   │
│  - 框架官方文档和最佳实践                │
│  来源: Context7 / 官方文档 MCP          │
└─────────────────────────────────────────┘

外部记忆机制：

• 长输出 → 保存到 .agent_memory/observations/
• 工作区状态 → 快照到 .agent_memory/state.md
• 当前目标 → 记录在 .agent_memory/goals.md

📊 预期收益

引入上下文工程（Context Engineering）后，你的 AI 编程体验将获得质的飞跃：

• 📉 Token 消耗降低 90%：通过将长输出（日志、数据、构建产物）卸载到外部文件系统，仅保留引用，大幅节省上下文窗口。
• 📈 准确率提升 40%：结构化的 .ai/skills 明确了团队规范，显著减少 AI "自作主张" 导致的错误。
• 🚀 采纳率提升：通过标准化项目结构，新加入的开发者（或新的 AI Session）能瞬间理解项目上下文。

🚀 快速开始

选择适合你的工具

工具	适用场景	安装方式
🐍 Python MCP	Claude Desktop + Python项目	pip install ctx-engine-mcp
📦 Node.js MCP	Claude Desktop + JS/TS项目	npx context-engineering-mcp
🔧 CLI工具	独立使用，无需AI工具	chmod +x ctx.py

方式1: Node.js MCP（推荐）

# 1. 配置 Claude Desktop
# 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "context-engineering": {
      "command": "npx",
      "args": ["-y", "context-engineering-mcp"]
    }
  }
}

方式2: Python MCP

# 1. 安装
pip install ctx-engine-mcp

# 2. 配置 Claude Desktop
# 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "context-engineering": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "ctx-engine-mcp",
        "context-mcp"
      ]
    }
  }
}
# 或者如果使用标准 pip 安装：
{
  "mcpServers": {
    "context-engineering": {
      "command": "python3",
      "args": ["-m", "context_mcp.server"]
    }
  }
}

方式3: CLI工具

# 1. 下载并安装
chmod +x packages/cli/ctx.py
ln -s $(pwd)/packages/cli/ctx.py /usr/local/bin/ctx

# 2. 初始化项目
ctx init

# 3. 生成工作区快照
ctx state --print

# 4. 包装长输出命令
ctx wrap npm install

� 使用场景示例

场景 1：重构遗留代码模块

问题：你需要重构一个复杂的遗留模块，代码量巨大，直接丢给 AI 会超出上下文限制，且容易破坏现有逻辑。

Context Engineering 解决方案：

1. 初始化：ctx init 创建标准结构。
2. 定义规范：在 .ai/skills/refactoring-guide.md 中定义重构原则（如 "保持函数纯度"、"错误处理规范"）。
3. 理解现状：AI 调用 get_workspace_state 获取全局视图，然后按需读取关键文件。
4. 执行重构：
   • AI 请求运行测试：ctx wrap npm test（结果存入 .agent_memory/observations/）。
   • AI 读取测试失败日志：read_observation("test_fail.log")（只读取错误部分）。
   • AI 修复代码并再次运行测试。

场景 2：新成员（AI）入职

问题：每次开启一个新的 AI Session，都要重复一遍 "我们要用 TypeScript，缩进用 2 空格..."。

Context Engineering 解决方案：

1. 项目根目录已有 .ai/skills/coding-standards.md。
2. AI 启动时自动通过 MCP 读取 .ai/skills 目录。
3. 结果：AI 第一行代码就完全符合团队规范，无需任何 Prompt 调教。

�📚 核心功能

1. 初始化上下文结构

# 创建标准目录结构
.ai/
└── skills/
    └── coding-standards.md    # 团队编码规范

.agent_memory/
├── goals.md                   # 当前目标
├── state.md                   # 工作区快照
├── observations/              # 长输出存储
└── context_cache/             # 上下文缓存

2. 工作区状态快照

AI可以随时调用 get_workspace_state 获取：

• 📋 当前目标（goals.md）
• 📁 目录结构（深度2层）
• 🔄 Git状态（未提交的修改）
• 📝 最近的commit

3. 长输出外部化

# 传统方式（占用大量token）
$ npm install
[10000行输出占用上下文窗口]

# 使用外部记忆
$ ctx wrap npm install
✅ Output saved to: .agent_memory/observations/20260121_npm_install.log
📊 Size: 50000 chars, 1200 lines
Preview (Head 10 lines):
...

4. 按需读取

AI只在需要时读取完整内容：

AI: "让我检查npm install的完整输出"
→ 调用 read_observation("20260121_npm_install.log")
→ 只在需要时加载，不占用常驻上下文

🛠️ 工具对比

特性	CLI工具	Python MCP	Node.js MCP
独立使用	✅	❌	❌
Claude集成	❌	✅	✅
自动调用	❌	✅	✅
跨平台	✅	✅	✅
安装难度	简单	中等	简单

📖 文档

• AI编程最佳实践 - 理论基础
• 文件系统作为外部记忆 - 实现对比
• Python MCP使用指南
• Node.js MCP使用指南
• CLI工具使用指南

🎓 核心理念

动态上下文 vs 静态上下文

❌ 静态上下文（低效）
启动时加载所有Skills → 200K tokens → AI处理缓慢

✅ 动态上下文（高效）
索引1K + 按需加载5K → 6K tokens → AI响应快速

文件系统作为外部记忆

传统方式：
所有信息都在上下文窗口 → 很快达到上限 → 开始"遗忘"

外部记忆方式：
核心信息在上下文 + 详细信息在文件 → 按需加载 → 永不遗忘

🤝 贡献

欢迎提交Issue和Pull Request！

开发设置

# 克隆仓库
git clone [email protected]:slicenferqin/ctx-mcp.git
cd ctx-mcp

# Python MCP开发
cd packages/python-mcp
pip install -e .

# Node.js MCP开发
cd packages/node-mcp
npm install
npm run build

📄 许可证

MIT License - 详见 LICENSE

🙏 致谢

本项目受以下工作启发：

• InfiAgent - 十步策略和嵌套注意力机制
• Manus - 可恢复压缩理念
• Cursor - 动态上下文发现

📮 联系

• GitHub Issues: 提交问题
• 讨论: GitHub Discussions

---

记住这个公式：

AI编程效果 = AI能力 × 上下文质量

AI的能力是固定的，但上下文质量是你可以控制的变量。