内容
# 上下文守护者 🧠
**带有完美记忆的模型上下文协议（MCP）服务器，用于人工智能辅助开发**
[](https://dotnet.microsoft.com/download/dotnet/9.0)
[](https://modelcontextprotocol.io)
[](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot)
[](https://github.com/chasecuppdev/contextkeeper-mcp/actions)
[](https://opensource.org/licenses/MIT)
上下文守护者通过解决会话之间上下文丢失的基本问题，彻底改变了人工智能辅助开发。它使用受LSM树启发的架构，维护了项目演变的完整、可搜索的历史记录，确保人工智能助手永远不会忘记。
## 🌟 主要功能
### 📸 全面的上下文捕获
- **开发快照**：捕获完整的项目状态，包括git上下文、工作区信息和文档
- **自动触发**：git钩子（pre-commit、post-checkout）自动捕获上下文
- **智能归档**：受LSM树启发的压缩技术，在保留历史记录的同时保持存储效率
- **里程碑跟踪**：使用有意义的里程碑标记快照，便于轻松引用
### 🤖 人工智能原生设计
- **自然语言搜索**：询问“我们何时添加了身份验证？”并立即获得答案
- **演变洞察**：跟踪组件如何从“计划”演变为“完成”
- **上下文感知分析**：智能关键词提取和建议
- **完美记忆**：您的AI助手在会话之间记住所有内容
### 🔧 模型上下文协议（MCP）工具
六种适用于AI助手的功能强大的工具：
- `snapshot` - 创建全面的上下文快照
- `search_evolution` - 通过项目历史记录进行自然语言搜索
- `track_component` - 跟踪随时间推移的功能演变
- `compare_snapshots` - 比较任意两个快照
- `get_status` - 系统状态，包含压缩洞察
- `get_timeline` - 项目演变的时序视图
### 💻 C# 代码智能
五种由Roslyn支持的代码分析工具：
- `FindSymbolDefinitions` - 定位符号声明
- `FindSymbolReferences` - 查找所有用法
- `NavigateInheritanceHierarchy` - 探索类型关系
- `SearchSymbolsByPattern` - 通配符模式匹配
- `GetSymbolDocumentation` - 提取XML文档
### 📝 用户工作区
通过Claude的@符号可访问的灵活文档区域：
- **需求**：存储项目规格和用户故事
- **设计**：记录架构决策和模式
- **指令**：自定义AI助手指南
- **自动捕获**：工作区文件包含在所有快照中
## 🚀 快速入门
### 安装
```bash
# 克隆仓库
git clone https://github.com/chasecuppdev/contextkeeper-mcp.git
cd contextkeeper-mcp
# 构建项目
dotnet build
# 作为MCP服务器运行
dotnet run --project src/ContextKeeper
```
### 基本用法
```bash
# 在项目中初始化上下文守护者
dotnet run --project src/ContextKeeper -- init
# 创建手动快照
dotnet run --project src/ContextKeeper -- snapshot "feature-complete"
# 搜索项目历史记录
dotnet run --project src/ContextKeeper -- search "authentication"
# 检查系统状态
dotnet run --project src/ContextKeeper -- check
```
### Git集成
```bash
# 安装git钩子以自动捕获
dotnet run --project src/ContextKeeper -- init --git-hooks
# 现在，快照将自动创建：
# - Pre-commit：在提交前捕获状态
# - Post-checkout：在分支切换后捕获状态
```
## 📁 架构
### 存储结构
```plaintext
.contextkeeper/
├── snapshots/ # 活动快照
│ ├── SNAPSHOT_2025-06-24_manual_feature-complete.md
│ └── SNAPSHOT_2025-06-24_git-commit_abc123.md
└── archived/ # 已压缩的历史记录
└── ARCHIVED_2024-01-01_2024-03-31_COMPACTED.md
context-workspace/ # 用户可访问的工作区（在Claude的@中可见）
├── workspace/ # 自定义文档
│ ├── requirements/ # 项目需求
│ ├── design/ # 设计决策
│ └── instructions/ # AI指令
└── project-history/ # 上下文守护者开发文档
```
### 快照格式
每个快照捕获：
- **Git上下文**：分支、提交、未提交的文件
- **工作区信息**：工作目录、最近的命令
- **文档**：所有markdown文件（CLAUDE.md、README.md等）
- **元数据**：时间戳、类型、里程碑、完整的JSON上下文
### 自动压缩
当以下条件满足时，会触发自动归档：
- 快照计数超过阈值（可配置，默认为20）
- 存在90天以上的快照
- 快照创建后进行非阻塞后台操作
## 🤝 MCP集成
### 与Claude Desktop集成
将以下内容添加到您的Claude Desktop配置（`~/.claude.json`）中：
```json
{
"mcpServers": {
"contextkeeper": {
"type": "stdio",
"command": "dotnet",
"args": ["run", "--project", "/path/to/contextkeeper/src/ContextKeeper"],
"env": {}
}
}
}
```
**重要**：确保：
1. 将`/path/to/contextkeeper`替换为实际的ContextKeeper安装路径
2. 在配置中包含`"type": "stdio"`
3. 将命令和参数保持为单独的字段（不要合并它们）
### 与其他MCP客户端集成
上下文守护者实现了标准的MCP协议，可以与任何兼容的客户端一起使用。服务器提供工具发现和基于JSON的通信。
## 🛠️ 配置
### 配置文件（`contextkeeper.config.json`）
```json
{
"version": "2.0",
"paths": {
"history": ".contextkeeper",
"snapshots": ".contextkeeper/snapshots",
"archived": ".contextkeeper/archived",
"userWorkspace": "context-workspace/workspace"
},
"snapshot": {
"dateFormat": "yyyy-MM-dd",
"filenamePattern": "SNAPSHOT_{date}_{type}_{milestone}.md",
"autoCapture": true,
"autoCaptureIntervalMinutes": 30
},
"compaction": {
"threshold": 20,
"maxAgeInDays": 90,
"autoCompact": true
},
"contextTracking": {
"trackOpenFiles": true,
"trackGitState": true,
"trackRecentCommands": true,
"documentationFiles": ["*.md"],
"ignorePatterns": ["node_modules", "bin", "obj", ".git"]
}
}
```
### 环境变量
- `CONTEXTKEEPER_PROFILE` - 覆盖自动检测的配置文件
- `CONTEXTKEEPER_DEBUG` - 启用调试日志记录
## 📊 性能和基准测试
### 原生AOT指标
- **启动时间**：~12ms（对比~200ms JIT）
- **二进制大小**：41MB独立可执行文件（含Roslyn）
- **内存使用**：18MB典型（对比JIT减少78%）
- **搜索速度**：<100ms适用于1000+快照
### 操作基准测试
```
快照创建： 8ms (10,000行)
搜索（1000个文档）： 45ms （全文）
压缩（100MB）： 280ms （70%大小减少）
符号搜索： 12ms (50K符号)
```
### 存储效率
- 原始快照：100MB → 压缩：28MB（72%减少）
- 重复数据删除率：85%适用于类似快照
- 压缩：Gzip实现3:1比例
## 🧪 开发
### 先决条件
- .NET 9.0 SDK
- Visual Studio 2022 或带有C#扩展的VS Code
### 从源代码构建
```bash
# 克隆仓库
git clone https://github.com/chasecuppdev/contextkeeper-mcp.git
cd contextkeeper-mcp
# 恢复依赖项
dotnet restore
# 构建
dotnet build
# 运行测试
dotnet test
# 构建原生AOT（需要特定于平台的SDK）
dotnet publish -c Release -r linux-x64 -p:PublishAot=true
```
### 测试
项目包含一套全面的测试套件，包含98个测试，涵盖：
- 核心功能（快照、搜索、演变跟踪）
- 压缩引擎和存储优化
- MCP协议实现
- Roslyn代码分析集成
- 集成场景
使用以下命令运行测试：
```bash
# 运行所有测试
dotnet test
# 详细输出运行测试
dotnet test --verbosity detailed
# 运行特定测试类别
dotnet test --filter "Category=Integration"
```
### 项目结构
```
contextkeeper-mcp/
├── src/
│ └── ContextKeeper/
│ ├── Config/ # 配置管理
│ ├── Core/ # 核心服务
│ ├── Protocol/ # MCP实现
│ ├── CodeAnalysis/ # Roslyn集成
│ └── Utils/ # 实用工具
├── tests/
│ └── ContextKeeper.Tests/ # 全面的测试套件
└── docs/ # 附加文档
```
## 🎯 快速演示
### 示例：“我们何时添加了身份验证？”
```bash
$ dotnet run -- search "authentication"
Found 3 matches across history:
2025-06-15: 在需求中首次提及（状态：计划中）
2025-06-18: 开始实施（状态：进行中）
2025-06-22: 完成JWT集成（状态：已完成）
```
### 示例：跟踪功能演变
```bash
$ dotnet run -- evolution "payment system"
Evolution Timeline:
└── 2025-06-10: 初始设计讨论
└── 2025-06-15: 定义API规范
└── 2025-06-20: 选择Stripe集成
└── 2025-06-25: 生产部署
```
## 🏗️ 技术深入探讨
### 受LSM树启发的架构
上下文守护者实现了日志结构合并树方法，以实现高效存储：
- **写入路径**：新快照追加到活动层（O（1）写入）
- **压缩**：后台合并减少存储70%
- **读取路径**：跨排序快照的二进制搜索（O（log n））
- **内存**：布隆过滤器用于快速存在检查
### 原生AOT编译
利用.NET 9的原生AOT进行生产性能：
```bash
# 编译为原生二进制文件（41MB，含Roslyn）
dotnet publish -c Release -r linux-x64 -p:PublishAot=true
# 启动比较：
# JIT：~200ms | AOT：~12ms（16倍更快）
# 内存：85MB → 18MB（78%减少）
```
### MCP协议实现
完整的模型上下文协议服务器，具有：
- JSON-RPC 2.0传输层
- 工具发现和自省
- 大型数据集流式响应
- 按照MCP规范进行错误处理
### Roslyn集成深入探讨
高级C#代码分析能力：
```csharp
// 示例：查找所有IRepository的实现
var implementations = await FindSymbolReferences("IRepository");
// 返回：UserRepository、ProductRepository、OrderRepository
// 导航继承层次结构
var hierarchy = await NavigateInheritance("BaseController");
// 返回完整的继承树，包含15个派生控制器
```
## 🤔 为什么选择上下文守护者？
### 问题
AI助手在会话之间会丢失上下文，迫使开发人员反复解释项目历史、架构决策和实现细节。
### 解决方案
上下文守护者维护了项目演变的完整、可搜索的历史记录。您的AI助手可以立即访问：
- 何时以及为什么添加了功能
- 组件如何随时间演变
- 历史上任何时刻的完整上下文
- 可自然语言搜索的文档
### 现实影响
最初从CodeCartographerAI中提取，上下文守护者在生产中证明了其价值：
- 减少80%的上下文重新解释
- 历史查询几乎实时（<1000个快照的100毫秒）
- 跨数月开发的完美回忆
- 无缝的AI助手集成
### 具体示例：调试生产问题
```
开发者：“我们何时更改了用户身份验证流程？”
AI（使用上下文守护者）：“根据历史记录：
- 6月15日：原始OAuth2实现
- 6月22日：添加2FA支持（提交abc123）
- 6月28日：切换到JWT令牌（安全审计）
6月28日的JWT更改可能与您的生产问题有关。”
```
## 🗺️ 路线图
### 近期
- [ ] 视觉时间线界面（Web UI）
- [ ] 上下文恢复（恢复完整的开发状态）
- [ ] VS Code扩展
- [ ] 增强的AI摘要
### 未来
- [ ] 团队同步
- [ ] 导出到Confluence/Notion
- [ ] TypeScript移植以适应更广泛的采用
- [ ] 指标仪表盘
## 🤝 贡献
欢迎贡献！请阅读我们的[贡献指南](CONTRIBUTING.md)，了解我们的行为准则和提交拉取请求的流程。
### 开发工作流
1. 分叉仓库
2. 创建功能分支（`git checkout -b feature/AmazingFeature`）
3. 提交更改（`git commit -m 'Add some AmazingFeature'`）
4. 推送到分支（`git push origin feature/AmazingFeature`）
5. 打开拉取请求
## 📄 许可证
该项目在MIT许可证下获得许可 - 有关详细信息，请参阅[LICENSE](LICENSE)文件。
## 🙏 致谢
- 使用[模型上下文协议](https://modelcontextprotocol.io)规范构建
- 由[Roslyn](https://github.com/dotnet/roslyn)提供C#代码分析支持
- 受LSM树存储架构启发
- 最初从[CodeCartographerAI](https://github.com/chasecuppdev/codecartographerai)提取
## 📞 支持
- **问题**：[GitHub Issues](https://github.com/chasecuppdev/contextkeeper-mcp/issues)
- **讨论**：[GitHub Discussions](https://github.com/chasecuppdev/contextkeeper-mcp/discussions)
- **文档**：[Wiki](https://github.com/chasecuppdev/contextkeeper-mcp/wiki)
---
**上下文守护者** - *再也不会丢失上下文* 🧠✨
