内容
# 开发上下文内存 MCP
一个本地优先的 MCP 服务器，为 AI 编程助手提供 **持久的、结构化的、可读的内存**，用于软件项目。
## 为什么？
AI 编程助手在会话之间会丢失上下文。他们重新读取文件，忘记决策，并错过约定。RAG 解决方案索引源代码 — 但源代码不是合适的内存单位。代理实际上需要的是 **持久的项目知识**：架构决策、API 合同、约定、错误和待办事项。
开发上下文内存将这些知识存储为项目内的 Markdown 文件，在 `.dev-context-memory/` 文件夹中。无需数据库，无需向量存储，无需云服务。只需您可以读取、编辑和提交的文件。
### 它与 RAG 的区别
| 方面 | 传统的 RAG | 开发上下文内存 |
|---|---|---|
| **来源** | 索引源代码 | 存储精选的项目知识 |
| **格式** | 向量数据库中的嵌入 | 人类可读的 Markdown |
| **位置** | 外部服务或本地数据库 | 项目内（`.dev-context-memory/`） |
| **持久性** | 在更改时重建 | Git 提交，始终可用 |
| **人类可读** | 否 | 是 — 使用任何文本编辑器编辑 |
| **内容** | 完整的代码 | 简洁的决策、合同、约定 |
## 内存部分
服务器管理这些 Markdown 文件：
| 部分 | 文件 | 目的 |
|---|---|---|
| `概述` | `overview.md` | 高级项目描述 |
| `架构` | `architecture.md` | 系统架构和设计模式 |
| `API 合同` | `api-contracts.md` | API 端点合同 |
| `决策` | `decisions.md` | 架构决策记录 |
| `错误` | `bugs.md` | 已知的错误和问题 |
| `待办事项` | `todos.md` | 计划的工作和任务 |
| `约定` | `conventions.md` | 编码标准和风格指南 |
| `词汇表` | `glossary.md` | 项目特定的术语 |
## MCP 工具
| 工具 | 描述 |
|---|---|
| `list_memory_sections` | 列出可用的内存部分 |
| `read_memory` | 读取内存部分 |
| `write_memory` | 覆盖内存部分（谨慎使用） |
| `append_decision` | 添加架构决策记录 |
| `append_api_contract` | 添加 API 端点合同 |
| `search_memory` | 按关键词搜索所有部分 |
| `summarize_memory` | 获取部分的标题和摘录 |
## 安装
```bash
# 克隆或复制到您的工具目录
cd dev-context-memory-mcp
# 安装依赖项
npm install
# 构建
npm run build
```
## 运行
服务器通过 **stdio** 进行通信，这是标准的 MCP 传输方式：
```bash
node dist/index.js
```
如果不存在，服务器将在当前工作目录中创建 `.dev-context-memory/` 文件夹。
## MCP 配置
### VS Code GitHub Copilot
添加到您的 `.vscode/mcp.json` 文件中：
```json
{
"servers": {
"dev-context-memory": {
"command": "node",
"args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"],
"cwd": "/absolute/path/to/your/project"
}
}
}
```
### Claude Desktop / Claude Code
添加到您的 MCP 设置中（例如，`claude_desktop_config.json` 或 `.claude/settings.json`）：
```json
{
"mcpServers": {
"dev-context-memory": {
"command": "node",
"args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"],
"cwd": "/absolute/path/to/your/project"
}
}
}
```
### Cursor
在项目根目录中添加到 `.cursor/mcp.json` 中：
```json
{
"mcpServers": {
"dev-context-memory": {
"command": "node",
"args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"]
}
}
}
```
### Gemini CLI / Antigravity
添加到您的 `.gemini/settings.json` 中：
```json
{
"mcpServers": {
"dev-context-memory": {
"command": "node",
"args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"],
"cwd": "/absolute/path/to/your/project"
}
}
}
```
> **重要：** 将 `cwd` 设置为要存储内存的项目的根目录。`.dev-context-memory/` 文件夹将在那里创建。
## 示例工具调用
### 列出可用部分
```json
{
"tool": "list_memory_sections",
"arguments": {}
}
```
### 读取部分
```json
{
"tool": "read_memory",
"arguments": {
"section": "architecture"
}
}
```
### 记录决策
```json
{
"tool": "append_decision",
"arguments": {
"title": "使用 PostgreSQL 存储用户数据",
"context": "我们需要一个关系数据库来存储用户配置文件、权限和审计日志。SQLite 对于生产环境中的并发访问来说太有限了。",
"decision": "使用 PostgreSQL 16 和 Drizzle ORM。为 MVP 部署在 Supabase 上。",
"consequences": "需要运行的 PostgreSQL 实例。添加 Drizzle 作为依赖项。需要迁移工具。",
"relatedFiles": ["src/db/schema.ts", "src/db/connection.ts", "docker-compose.yml"]
}
}
```
### 记录 API 合同
```json
{
"tool": "append_api_contract",
"arguments": {
"name": "创建用户",
"method": "POST",
"path": "/api/v1/users",
"purpose": "创建新的用户帐户并发送欢迎电子邮件。",
"auth": "Bearer token，需要管理员角色",
"request": "{ email: string, name: string, role: 'admin' | 'user' }",
"response": "{ id: string, email: string, createdAt: string }",
"sideEffects": "通过 SendGrid 发送欢迎电子邮件。创建 Stripe 客户。",
"frontendUsage": "从管理员仪表盘用户创建表单调用。",
"relatedFiles": ["src/routes/users.ts", "src/services/email.ts"]
}
}
```
### 搜索内存
```json
{
"tool": "search_memory",
"arguments": {
"query": "PostgreSQL"
}
}
```
### 总结所有内存
```json
{
"tool": "summarize_memory",
"arguments": {}
}
```
## 与 `AGENTS.md` 推荐用法
为了帮助 AI 代理了解如何以及何时使用内存 MCP 服务器，强烈建议在项目工作空间中包含说明。
我们已在存储库中附带的 `AGENTS.md` 文件中提供了这些说明的综合示例。
您可以复制 `AGENTS.md` 的内容并将其添加到您自己的项目的 `AGENTS.md`、`.cursorrules`、`.github/copilot-instructions.md` 或编辑器支持的任何等效代理说明文件中。这确保代理遵循有关内存质量、安全性和何时信任内存而非源代码的最佳实践。
## 安全模型
开发上下文内存默认设计为 **安全**:
- **文件系统隔离**：所有读取和写入操作都限定在 `.dev-context-memory/` 中。阻止路径遍历。
- **部分白名单**：仅接受已知的部分名称。未知部分会被明确错误拒绝。
- **无 shell 执行**：服务器从不运行 shell 命令。
- **无网络访问**：服务器从不进行网络请求。
- **无静默删除**：写入操作是显式的，并有明确的文档记录。
- **无任意文件访问**：服务器无法读取或写入项目源文件。
- **输入验证**：在使用之前验证所有输入。
## 开发
```bash
# 监视模式用于开发
npm run dev
# 构建生产环境
npm run build
```
## 手动测试
1. 构建项目：`npm run build`
2. 在项目目录中运行服务器：
```bash
cd /path/to/your/project
node /absolute/path/to/memory-mcp/dist/index.js
```
3. 服务器在 stdio 上启动。您可以使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 测试它：
```bash
npx @modelcontextprotocol/inspector node /absolute/path/to/memory-mcp/dist/index.js
```
> **小贴士：修复旋转令牌问题**
> MCP Inspector 使用授权令牌保护其本地浏览器 UI。当您使用 `npx @modelcontextprotocol/inspector` 启动 Inspector 时，它可能会每次生成一个新的随机令牌。这意味着每次重启可能需要打开新的 URL、复制新的令牌或重新连接浏览器会话，这在重复测试工具时可能会很烦人。
>
> 该项目包含一个 `inspector` 脚本，设置了一个稳定的本地开发令牌（`stable-token-123`），使用 `MCP_PROXY_AUTH_TOKEN`。通过 npm 的 `--prefix` 标志运行它，以便您可以从目标项目启动脚本，同时使用此存储库的包脚本：
> ```bash
> npm --prefix /absolute/path/to/memory-mcp run inspector
> ```
4. 检查是否创建了 `.dev-context-memory/` 并带有默认模板文件。
5. 使用 Inspector UI 调用 `list_memory_sections`、`read_memory` 和 `append_decision` 等工具。
## 未来改进
- **基于嵌入的搜索**：用语义搜索替换关键词匹配。
- **Git 集成**：自动提交内存更改、跟踪历史、检测漂移。
- **部分版本控制**：保留内存编辑的更改日志。
- **自定义部分**：允许项目定义自己的部分。
- **内存验证**：检查内存文件的结构和完整性。
- **跨项目内存**：在多个存储库中共享约定。
- **冲突解决**：检测和显示冲突的决策或过时的合同。
- **MCP 资源**：将内存部分作为 MCP 资源公开，供只读访问。
