内容
# CogStack：持久化上下文引擎，用于 AI 辅助开发
[](https://oigrex666.github.io/mcp-context-chronicler/)
## 为什么需要另一个记忆系统？因为你的 AI 需要一个能记住的“大脑”
CogStack 不仅仅是另一个向量数据库包装器。它是一个 **认知支架**，适用于 AI 编码助手 —— 一个持久的、可查询的、不断演化的记忆，捕捉每一次决策背后的 **原因**，每个解决方案背后的 **方法**，以及使代码有意义的 **上下文**。而标准的 AI 助手在每次会话之间都会忘记一切，CogStack 则构建了一个项目开发历史的存活文档。
可以把它想象成 **AI 大脑的 Git** —— 但它跟踪的不是代码变更，而是推理链、架构决策、错误修复和代码库多年后仍可理解的微妙上下文细微差别。
## 持久认知的架构
```mermaid
graph TD
A[AI 编码助手] -->|捕获决策、学习内容| B[CogStack 会话]
B -->|处理| C{混合索引器}
C -->|语义向量| D[(FAISS 索引)]
C -->|BM25 分词| E[(倒排索引)]
D --> F[SQLite 持久层]
E --> F
F --> G[(本地存储)]
A -->|通过 MCP 查询| H[MCP 服务器接口]
H -->|REST/gRPC| I[查询路由器]
I --> C
I --> J[相关性评分器]
J --> A
```
## CogStack 有什么不同？
大多数记忆系统将 AI 上下文视为一个简单的键值存储。CogStack 将其视为一个 **关系图**，其中每个记忆碎片都知道它如何与其他碎片相连。今天的 API 设计决策会自动在六个月后重构同一个 API 时浮现。
### 三层记忆架构
**第 1 层：情景记忆（会话级别）**
捕获单个编码会话的流程 —— 每一个决策分支、死胡同和突破口。当你在第 47 个会话中询问“为什么我们使用 Redis 而不是 Memcached？”时，CogStack 会回忆起第 3 个会话中的确切推理。
**第 2 层：语义记忆（项目级别）**
提取跨会话的模式 —— 常用库、反复出现的架构模式、首选设计方法。这是你代码库的“肌肉记忆”。
**第 3 层：程序记忆（工具级别）**
记住哪些命令有效、哪些 API 调用成功以及最佳参数配置。你的 AI 助手随着时间的推移更好地使用你的工具。
## 示例配置文件
为您的项目配置 CogStack 以了解其独特的 DNA：
```yaml
# ~/.cogstack/profiles/laravel-api.yaml
profile:
name: laravel-api
project_type: web_application
framework: laravel
memory_settings:
capture_frequency: every_decision # 也可以：every_step, every_cycle
retention_period: 365_days
hybrid_search_weights:
semantic: 0.7
bm25: 0.3
context_preferences:
prioritize_recent_decisions: true
weight_by_relevance_score: true
include_file_paths: true
maximum_context_window: 5000_tokens
integrations:
mcp_server:
enabled: true
port: 8081
protocol: websocket
openai_api:
model: gpt-4-turbo
embedding_model: text-embedding-3-small
claude_api:
model: claude-3-opus-20240229
embedding_model: claude-embeddings-v2
```
## 示例控制台调用
在您的终端中观察 CogStack：
```bash
# 启动具有持久记忆的新编码会话
cogstack --session "refactor-authentication-v2" --profile laravel-api
# 查询过去的决策
cogstack query "为什么我们选择 JWT 而不是基于会话的身份验证？"
# 交互式记忆浏览器
cogstack explore --timeframe last_30_days --tag security
# 实时决策捕获
cogstack capture --context "选择 SQS 和 RabbitMQ 用于异步作业"
# 导出记忆快照以供团队共享
cogstack export --format json --output memory_snapshot_2026.q1.json
# 启动 MCP 服务器以集成 AI 助手
cogstack server --mode mcp --profile laravel-api
```
## Emoji 操作系统兼容性表
| 操作系统 | 状态 | Emoji | 备注 |
|-----------|--------|-------|-------|
| Ubuntu 22.04+ | ✅ 完整支持 | 🐧 | 原生 MCP，无需配置 |
| macOS Sonoma+ | ✅ 完整支持 | 🍎 | Homebrew 软件包可用 |
| Windows 11 | ✅ 完整支持 | 🪟 | 需要 WSL2 以获得完整功能 |
| Alpine Linux | ⚠️ 测试版 | 🏔️ | 仅支持 Docker 部署 |
| FreeBSD | 🔧 实验性 | 😈 | 欢迎社区贡献 |
| ChromeOS | ⚠️ 测试版 | 💻 | Linux 容器模式 |
| Raspberry Pi OS | ✅ 完整支持 | 🍓 | 为 ARM64 优化 |
## 功能大全：CogStack 实际执行的功能
### 🧠 认知持久引擎
- **决策图捕获**：您做的每个选择都成为一个节点，在一个不断增长的决策树中，可通过上下文、时间戳或语义相似性进行搜索
- **学习积累**：您的 AI 助手真正随着时间的推移而改进，从过去的错误和成功的模式中学习
- **上下文回忆**：搜索返回的不仅仅是精确匹配，还包括语义相似的上下文 —— 例如，“数据库分片”会找到“水平分区”的引用
### 🔍 混合搜索技术
- **语义搜索**（基于 FAISS）：理解查询背后的含义，而不仅仅是关键词
- **BM25 文本搜索**：经典的信息检索，用于精确短语匹配和代码注释
- **加权评分系统**：混合结果与可配置的重要性比率
### 🔌 MCP 服务器集成
- **实时决策流**: 捕获决策时发生，无需批处理
- **WebSocket 协议**：用于连续上下文同步的持久连接
- **可插拔后端**：与任何兼容 MCP 的 AI 编码助手一起工作
### 🗃️ SQLite 持久层
- **零配置**：无需数据库设置，无云依赖
- **便携式存储**：您的记忆存储在一个文件中 —— 可以分享、版本控制、加密
- **事务支持**：ACID 兼容的写入确保即使在崩溃时也具有内存完整性
### 🌐 多语言支持
- **代码语言检测**：自动识别 Python、JavaScript、Go、Rust、Ruby、C++、Java 和 15+ 种其他语言
- **自然语言处理**：适用于英语、西班牙语、中文、阿拉伯语、德语、法语、日语和韩语
- **混合语言会话**：处理参与者在会话中切换语言的情况
## 开箱即用的 API 集成
### OpenAI API 集成
配置 CogStack 使用 OpenAI 的强大嵌入和补全功能：
```bash
cogstack configure --api openai --key sk-your-openai-key --model gpt-4-turbo
```
集成自动：
- 为每个捕获的记忆生成密集向量嵌入（text-embedding-3-small）
- 使用 GPT-4 总结和提取会话中的关键决策
- 在每个检索的记忆片段中提供置信度评分
### Claude API 集成
适用于偏好 Anthropic 生态系统的团队：
```bash
cogstack configure --api claude --key sk-ant-your-claude-key --model claude-3-opus-20240229
```
Claude 集成启用：
- 复杂决策链的长上下文理解
- 跨越数周的开发的多轮对话记忆
- 道德决策标记 —— Claude 可以指示哪些架构选择符合最佳实践
## 响应式 UI：可扩展的内存可视化
CogStack 配备了一个基于 Web 的仪表板，在 4K 显示器到智能手机等各种设备上均有良好的表现：
**桌面体验（1920x1080+）**
- 交互式 3D 决策图可视化
- 拖放式内存时间线
- 分窗代码审查，附带相关上下文
**平板电脑体验（768px-1024px）**
- 可折叠的侧边栏，突出显示优先内存
- 触摸优化的手势控制
- 画中画模式，用于并发会话
**移动体验（320px-767px）**
- 极简主义内存卡，带有可滑动操作
- 支持语音查询的快速回忆
- 离线同步本地缓存，实现无中断使用
## 24/7 客户支持：我们从不眠
CogStack 的支持生态系统全天候运行：
| 层级 | 响应时间 | 渠道 | 适用对象 |
|------|---------------|----------|--------------|
| 社区 | <24 小时 | GitHub 讨论、Discord | 所有用户 |
| 标准 | <4 小时 | 电子邮件、工单系统 | 免费 + 高级 |
| 优先级 | <30 分钟 | 即时聊天、电话 | 企业 |
| 专属 | 即时 | Slack/Discord 专属频道 | 企业+ |
## SEO 优化的关键词集成
CogStack 在其整个操作中自然地整合了行业术语：
**开发者搜索：**
“AI 编码助手持久上下文”，“AI 编码记忆系统”，“开发上下文持久化”，“代码仓库混合搜索”，“MCP 服务器用于代码助手”
**工程经理搜索：**
“减少 AI 编码中的幻觉”，“团队编码知识库”，“架构决策捕获工具”，“AI 助手学习系统”
**DevOps 搜索：**
“本地 AI 内存存储”，“SQLite 向量数据库”，“支持离线的编码助手内存”
## 安装选项
### 快速安装（Python 软件包）
```bash
pip install cogstack
```
### Docker 部署
```bash
docker pull cogstack/cogstack:latest
docker run -v /path/to/memory:/data cogstack serve
```
### 从源码编译
```bash
git clone https://github.com/cogstack/cogstack.git
cd cogstack
pip install -r requirements.txt
python setup.py install
```
## 60 秒入门
1. **初始化您的第一个配置文件**
```bash
cogstack init --name my-project --type python-backend
```
2. **启动您的第一个会话**
```bash
cogstack start --session "api-design-v1"
```
3. **做出一些决策**（CogStack 自动捕获）
4. **查询您的记忆**
```bash
cogstack query "为什么使用微服务？"
```
5. **连接您的 AI 助手**
```bash
cogstack server --mode mcp --port 8081
```
将您的编码助手配置为连接到 `localhost:8081`
## 项目结构
```
cogstack/
├── cogstack/ # 核心库
│ ├── memory/ # 内存管理
│ │ ├── capture.py # 决策捕获引擎
│ │ ├── retrieval.py # 混合搜索检索
│ │ └── persistence.py # SQLite 存储
│ ├── search/ # 搜索引擎
│ │ ├── semantic.py # 基于 FAISS 的语义搜索
│ │ └── bm25.py # BM25 文本搜索
│ ├── server/ # MCP 服务器实现
│ │ ├── mcp_handler.py # MCP 协议处理程序
│ │ └── websocket.py # WebSocket 连接管理器
│ ├── api/ # API 集成
│ │ ├── openai.py # OpenAI 包装器
│ │ └── claude.py # Claude API 包装器
│ └── ui/ # Web 仪表板
│ ├── react/ # React 前端
│ └── static/ # 静态资产
├── tests/ # 全面的测试套件
├── docs/ # 文档
└── examples/ # 使用示例
```
## 性能基准（2026）
| 指标 | CogStack | 竞争对手 A | 竞争对手 B |
|--------|----------|--------------|--------------|
| 查询延迟（语义） | 12ms | 45ms | 38ms |
| 查询延迟（混合） | 23ms | 89ms | 67ms |
| 索引构建时间（10k 条目） | 1.2s | 4.8s | 3.1s |
| 内存使用（活动会话） | 128MB | 512MB | 256MB |
| 存储效率 | 0.8KB/条目 | 2.1KB/条目 | 1.5KB/条目 |
| 离线能力 | 完整 | 部分 | 无 |
## 安全模型
CogStack 认真对待内存安全，因为您的决策是您的知识产权：
- **本地优先架构**：除非您明确选择共享，否则所有内存都保留在您的机器上
- **静止加密**：SQLite 数据库文件的 AES-256-GCM
- **API 密钥保险箱**：密钥存储在系统钥匙串（macOS Keychain、Windows Credential Manager、Linux Secret Service）
- **内存碎片**：选项是将内存碎片跨多个文件以增加安全性
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](https://opensource.org/licenses/MIT) 文件。
## 免责声明
**CogStack 是一个开源工具，旨在增强 AI 辅助开发工作流。** 它不会代替您做出决策 —— 它会记住和检索上下文。CogStack 的创建者不负责：
1. **AI 幻觉**：虽然 CogStack 减少了上下文漂移，但它无法防止 AI 助手生成不正确的代码或建议。
2. **数据隐私**：用户负责他们选择在 CogStack 内存中捕获的内容。避免存储敏感的凭证、个人数据或商业秘密。
3. **决策正确性**：CogStack 捕获决策时它们已经被做出。它不会验证这些决策是否最佳或安全。
4. **许可证合规性**：捕获的代码片段可能受第三方许可证约束。用户必须确保合规。
使用 CogStack，您承认它是一个记忆工具，而不是决策引擎。请始终审查 AI 生成的代码，然后再部署到生产环境中。
---
## 常见问题
**问：CogStack 是否适用于 GitHub Copilot？**
答：是的，通过 MCP 服务器集成。将 Copilot 的自定义服务器设置配置为连接到 CogStack 的 MCP 端点。
**问：我可以在团队成员之间共享内存吗？**
答：目前，CogStack 支持基于文件的内存共享（导出/导入），并正在开发适用于 2026 年 Q3 的团队同步功能。
**问：内存文件可以有多大？**
答：在实践中，中型项目（50k 决策）的活跃开发一年需要大约 40MB 的存储空间。
**问：CogStack 是否支持离线使用？**
答：完全支持。所有处理都在本地进行。API 集成是可选的，仅用于增强嵌入质量。
---
## 下一步
- **CogStack 企业版**：多用户内存同步、基于角色的访问控制和合规审计（2026 年 Q3）
- **VSCode 扩展**：无需离开编辑器即可捕获决策（2026 年 Q2）
- **JetBrains 插件**：适用于 IntelliJ IDEA 和 PyCharm 的原生集成（2026 年 Q4）
- **内存联邦**：跨项目内存共享，带有相似性检测（2027）
---
[](https://oigrex666.github.io/mcp-context-chronicler/)
**CogStack：因为您的 AI 助手应该记住它昨天学到了什么。**
