DevMind MCP

为AI助手打造的智能上下文感知记忆系统

English | 中文 | 更新日志 | 最新版本

为什么选择 DevMind MCP?

纯 MCP 工具 - 通过模型上下文协议与 AI 助手无缝集成
混合搜索 - 语义 40% + 关键词 30% + 质量 20% + 新鲜度 10%
100% 私密 - 所有数据本地存储在 SQLite，零云端传输
15 个 MCP 工具 - 完整的记忆管理和代码库索引工具集
跨平台支持 - 兼容 Claude Code、Cursor 及所有 MCP 客户端

概览

什么是 DevMind MCP?

DevMind MCP 通过模型上下文协议(MCP)为AI助手提供持久性记忆功能。它使AI能够跨对话记住上下文,自动跟踪开发活动,并智能检索相关信息。

核心特性

主要功能

智能记忆 - AI 助手在每次代码编辑后自动调用 record_context 工具记录变更
语义搜索 - AI驱动的向量嵌入搜索,查找相关上下文
代码库索引 - 索引项目文件用于语义搜索和代码发现
持久存储 - 基于SQLite的本地存储,完全私密
混合搜索 - 结合关键词和语义搜索,获得最佳结果
实时响应 - 开发过程中记录,即时检索
跨工具支持 - 兼容多个MCP客户端和开发环境
统一会话 - 每个项目一个主会话,保持上下文一致

技术特性

完整的MCP协议实现
统一会话管理(每个项目一个主会话)
自动会话重新激活
可自定义存储路径和行为
高效处理数千个上下文
自动清理和内存优化
健壮的错误处理和恢复

架构设计

┌──────────────────────────────────────────────────────────────┐
│                      AI Assistant                            │
│               (Claude Code / Cursor / etc.)                  │
└────────────────────────┬─────────────────────────────────────┘
                         │ MCP Protocol (stdio)
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                   DevMind MCP Server                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐  │
│  │  15 MCP Tools   │  │ Type-Based      │  │ Hybrid Search│  │
│  │                 │  │ Auto-Memory     │  │              │  │
│  │ • Session (4)   │  │                 │  │ • Semantic   │  │
│  │ • Context (6)   │  │                 │  │ • Keyword    │  │
│  │ • Project (3)   │  │ • 3 Tiers       │  │ • Quality    │  │
│  │ • Codebase (2)  │  │ • Smart Types   │  │ • Freshness  │  │
│  │ • Visualize (1) │  │ • Lazy Scoring  │  │              │  │
│  └─────────────────┘  └─────────────────┘  └──────────────┘  │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                  SQLite Local Storage                        │
│  Projects • Sessions • Contexts • Relationships • Embeddings │
│  + Auto-generated quality scores (lazy update every 24h)     │
└──────────────────────────────────────────────────────────────┘

核心组件:

15 个 MCP 工具 - 会话管理 (4)、上下文操作 (6)、项目功能 (3)、代码库索引 (2)、可视化 (1)
类型驱动自动记忆 - 基于上下文类型的简化3层策略
混合搜索 - 多维度评分：语义 40% + 关键词 30% + 质量 20% + 新鲜度 10%
本地存储 - SQLite 数据库，包含向量嵌入和全文搜索索引

📍 项目结构

devmind-mcp/
├── src/
│   ├── mcp-server.ts                # MCP协议服务器
│   ├── database.ts                  # SQLite存储引擎
│   ├── vector-search.ts             # 语义搜索（嵌入向量）
│   ├── session-manager.ts           # 会话与上下文管理
│   ├── pending-memory-tracker.ts    # 未记录文件追踪 (v2.2.6+)
│   ├── content-extractor.ts         # 代码分析与提取
│   ├── content-quality-assessor.ts  # 内容质量评分
│   ├── quality-score-calculator.ts  # 多维度质量评分
│   ├── auto-record-filter.ts        # 智能去重
│   ├── context-file-manager.ts      # 文件变更追踪
│   ├── performance-optimizer.ts     # 性能优化器 (v2.2.0+)
│   ├── search-cache.ts              # 搜索缓存
│   ├── smart-confirmation-system.ts # 智能确认系统
│   ├── types.ts                     # 类型定义
│   ├── index.ts                     # 主入口
│   │
│   ├── memory-graph/                # 记忆图谱可视化
│   │   ├── index.ts                 # 图谱生成器主入口
│   │   ├── types.ts                 # 图谱类型定义
│   │   ├── data/
│   │   │   ├── GraphDataExtractor.ts  # 数据库数据提取
│   │   │   ├── NodeBuilder.ts         # 节点构建与标签生成
│   │   │   └── EdgeBuilder.ts         # 边/关系构建
│   │   └── templates/
│   │       ├── HTMLGenerator.ts       # HTML可视化生成器
│   │       └── HTMLGeneratorCytoscape.ts  # Cytoscape图谱生成器
│   │
│   ├── utils/
│   │   ├── file-path-detector.ts    # 智能文件检测
│   │   ├── git-diff-parser.ts       # Git diff解析
│   │   ├── path-normalizer.ts       # 跨平台路径处理
│   │   ├── project-root-finder.ts   # 项目根目录查找 (v2.1.11+)
│   │   ├── language-detector.ts     # 编程语言检测
│   │   ├── query-enhancer.ts        # 搜索查询增强 (v2.2.0+)
│   │   ├── auto-memory-classifier.ts # 自动记忆分类 (v2.2.0+)
│   │   ├── context-enricher.ts      # 上下文增强 (v2.2.0+)
│   │   ├── batch-processor.ts       # 批处理器 (v2.2.0+)
│   │   └── performance-optimizer.ts # 性能优化 (v2.2.0+)
│   │
│   ├── context-engine/              # 代码库索引引擎
│   │   ├── index.ts                 # ContextEngine 主入口
│   │   ├── FileScanner.ts           # 文件扫描与过滤
│   │   ├── IgnoreProcessor.ts       # .gitignore 和 .augmentignore 规则
│   │   └── types.ts                 # 类型定义
│   │
│
├── dist/                            # 编译输出
├── scripts/                         # 维护脚本
├── docs/zh/                         # 中文文档
└── tests/                           # 测试文件


---

## 快速开始

### 环境要求

- **Node.js** ≥ 20.0.0
- **MCP兼容客户端** (Claude Code、Cursor等)

### 安装

选择适合您的安装方式:

| 安装方式     | 命令                         | 适用场景          | 自动更新 |
|:-------------|:-----------------------------|:------------------|:--------:|
| **NPX**      | `npx -y devmind-mcp@latest`  | 快速测试、首次使用 |    是    |
| **全局安装** | `npm install -g devmind-mcp` | 日常开发          |    否    |
| **源码安装** | `git clone + npm install`    | 贡献代码、定制开发 |    否    |

### 逐步配置

#### 步骤 1: 添加到 MCP 客户端

**方式 A: 使用 Claude Code CLI (最简单)**

```bash
# 安装最新版本
claude add mcp npx -y devmind-mcp@latest

# 或安装特定版本
claude add mcp npx -y devmind-mcp@2.4.1

方式 B: 手动配置

编辑您的MCP客户端配置文件:

配置文件位置:

Windows: C:\Users\<用户名>\.claude.json 或 %USERPROFILE%\.claude.json
macOS: ~/.claude.json
Linux: ~/.claude.json

添加以下配置:

{
  "mcpServers": {
    "devmind": {
      "command": "npx",
      "args": ["-y", "devmind-mcp@latest"]
    }
  }
}

使用全局安装? 替换为: {"command": "devmind-mcp"}

步骤 2: 重启 MCP 客户端

重启Claude Code或您的MCP客户端以加载DevMind。

步骤 3: 尝试第一个命令

在您的AI助手中尝试:

"使用 semantic_search 查找有关身份验证的信息"

完成! DevMind现在正在用持久记忆增强您的AI。

下一步

阅读使用指南了解可用工具
查看配置设置了解智能记录规则
探索使用场景获取灵感

AI 如何使用 DevMind

每次开发会话遵循以下步骤：

会话初始化
- 调用 get_current_session 或让其自动创建
- 说"检查记忆中..."并调用 list_contexts(limit: 5)
开发过程中
- 关键: 编辑文件后立即调用 record_context
- 根据工作类型使用: bug_fix, feature_add, code_modify
- 内容必须使用项目语言（中文/英文）
完成任务前
- 在说"完成"之前先记录
- 多文件修改使用 files_changed
用户询问历史时
- 使用 semantic_search 进行智能查询
- 使用 list_contexts 进行时间顺序浏览
- 使用 get_context 查看完整详情

使用指南

MCP工具速查

DevMind为您的AI助手提供 15个强大工具:

代码库索引

工具	用途	使用示例
`codebase`	索引项目文件用于语义搜索	索引整个代码库
`delete_codebase_index`	删除项目的代码库索引	清理已索引文件

注意: codebase 工具支持 .gitignore 和 .augmentignore 排除模式。同时还包含内置默认规则，自动排除常见目录如 node_modules/、dist/、build/、.git/ 等。

项目管理

工具	用途	使用示例
`list_projects`	[RECOMMENDED] 列出所有项目和统计信息	查看跟踪项目
`cleanup_empty_projects`	清理没有记忆的空项目记录	清理无用项目数据

会话管理

工具	用途	使用示例
`create_session`	创建新的开发会话	开始新功能开发
`get_current_session`	获取当前活跃会话信息	检查当前上下文
`end_session`	结束开发会话	完成工作
`delete_session`	删除会话及所有上下文	清理旧会话

注意: DevMind自动管理每个项目的主会话。会话会在需要时自动创建并跨对话重新激活。

上下文操作

|| 工具 | 用途 | 使用示例 | ||------------------|---------------------|-----------------| || record_context | 存储开发上下文 | 保存bug修复方案 | || list_contexts | 列出所有上下文 | 查看项目历史 | || delete_context | 删除特定上下文 | 移除过时信息 | || update_context | 更新上下文内容/标签 | 完善文档 |

搜索与发现

|| 工具 | 用途 | 使用示例 | ||-------------------|--------------------------|------------------| || semantic_search | AI驱动的语义搜索 | 查找相关实现 | || get_context | 根据ID获取记忆内容 | 查看完整记忆详情 |

注意: Embedding自动生成于record_context。质量评分在搜索时自动更新（懒加载，每24小时）。

可视化

工具	用途	使用示例
`export_memory_graph`	导出垂直时间轴图谱 (v1.19)	6列类型分组的时间轴可视化

v1.19 新功能：记忆图谱采用清晰的垂直时间轴布局，固定节点位置，性能优化。

ContextEngine (v2.4.9 新功能)

ContextEngine 是一个强大的代码库索引系统，能够自动扫描和索引整个项目，为智能搜索和代码发现提供支持。

核心特性

全面文件扫描 - 递归扫描所有项目文件，支持 20+ 种编程语言
智能过滤 - 自动应用忽略规则，排除无关文件和目录
增量索引 - 基于 SHA-256 哈希仅重新索引变更文件，提高效率
独立存储 - 使用独立的 file_index 表，避免污染开发记忆
二进制文件检测 - 自动跳过二进制文件（图像、可执行文件等）
语言检测 - 自动检测并分类编程语言

工作原理

项目目录
    │
    ▼
┌─────────────────────┐
│   文件扫描器        │  1. 递归扫描所有文件
│                     │  2. 应用忽略规则
│   - 递归扫描        │  3. 检测文件类型
│   - 文件过滤        │  4. 跳过二进制文件
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  忽略处理器         │  1. 应用忽略规则
│                     │  2. 过滤文件
│   - 智能过滤        │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  数据库存储         │  1. 存储到 file_index 表
│                     │  2. 生成文件哈希
│   - file_index      │  3. 索引以便搜索
│   - SHA-256 哈希    │
└─────────────────────┘

默认排除项

ContextEngine 自动排除以下常见目录和文件：

版本控制: .git/, .svn/, .hg/
依赖包: node_modules/, vendor/, .composer/
构建输出: dist/, build/, out/, .next/, .vite/, target/
日志和临时文件: *.log, *.tmp, *.temp, .DS_Store, Thumbs.db
IDE 文件: .vscode/, .idea/, *.swp
覆盖率报告: coverage/, .nyc_output/, .pytest_cache/

使用示例

// 索引整个代码库
await codebase({
  project_path: "/path/to/my-project"
});

// 强制重新索引所有文件
await codebase({
  project_path: "/path/to/my-project",
  force_reindex: true
});

// 索引后，使用 semantic_search 进行查询
const results = await semantic_search({
  query: "身份验证是如何实现的？",
  project_path: "/path/to/my-project"
});

与语义搜索的集成

索引完成后，ContextEngine 的文件会自动包含在 semantic_search 结果中，与开发记忆上下文一起。这使 AI 助手能够：

在代码库中找到特定实现
理解项目不同部分如何协同工作
从实际文件中检索代码模式和示例
回答关于项目架构的问题

使用示例

存储上下文信息

// 存储开发上下文
await record_context({
  content: "使用JWT令牌和刷新令牌实现用户身份验证",
  type: "implementation",
  tags: ["auth", "jwt", "security", "api"]
});

搜索和检索

// 查找相关上下文
const results = await semantic_search({
  query: "我们是如何实现身份验证的?",
  limit: 10
});

更新现有上下文

// 更新上下文信息
await update_context(contextId, {
  content: "更新身份验证以支持OAuth2和SAML",
  tags: ["auth", "jwt", "oauth2", "saml", "security"]
});

上下文化搜索

// 在特定时间范围内搜索
const results = await semantic_search({
  query: "数据库优化",
  timeRange: { days: 7 }
});

配置设置

基础配置（可选）

DevMind 开箱即用，具有合理的默认配置。配置文件是完全可选的。

如果需要自定义行为，可以在项目根目录创建 .devmind.json:

{
  "database_path": "~/.devmind/memory.db",
  "quality_threshold": 0.3,
  "embedding_model": "local",
  "auto_save_interval": 30000,
  "ignored_patterns": [
    "node_modules/**",
    ".git/**",
    "dist/**",
    "build/**"
  ],
  "included_extensions": [
    ".js",
    ".ts",
    ".py",
    ".go"
  ]
}

配置选项

选项	类型	默认值	描述
`database_path`	string	`~/.devmind/memory.db`	SQLite数据库文件位置
`quality_threshold`	number	`0.3`	上下文存储的最低质量分数
`embedding_model`	string	`"local"`	向量搜索的嵌入模型
`auto_save_interval`	number	`30000` (30秒)	自动保存间隔（毫秒）
`ignored_patterns`	string[]	参见上方示例	要忽略的glob模式
`included_extensions`	string[]	参见上方示例	要包含的文件扩展名

完整MCP配置示例

使用NPX (推荐):

{
  "mcpServers": {
    "devmind": {
      "command": "npx",
      "args": ["-y", "devmind-mcp@latest"]
    }
  }
}

使用全局安装:

{
  "mcpServers": {
    "devmind": {
      "command": "devmind-mcp"
    }
  }
}

重要提示: 配置更改后需要重启MCP客户端。

API参考

核心方法

`record_context(context: ContextData): Promise<string>`

存储新的上下文信息。

参数:

content (string) - 主要内容文本
type (string) - 内容类型: solution、code、error、documentation、test、configuration
tags (string[]) - 关联标签
metadata (object) - 附加元数据

返回: 上下文ID字符串

示例:

const id = await record_context({
  content: "修复WebSocket连接处理器中的内存泄漏",
  type: "solution",
  tags: ["websocket", "memory-leak", "bug-fix"]
});

`semantic_search(query: SearchQuery): Promise<Context[]>`

使用语义理解搜索相关上下文。

参数:

query (string) - 搜索查询
limit (number) - 最大结果数 (默认: 20)
type (string) - 按内容类型过滤
tags (string[]) - 按标签过滤
timeRange (object) - 时间范围过滤: { days: 7 }

返回: 匹配上下文数组

示例:

const results = await semantic_search({
  query: "身份验证实现",
  limit: 10,
  type: "implementation"
});

`update_context(id: string, updates: Partial<ContextData>): Promise<boolean>`

更新现有上下文。

示例:

await update_context(contextId, {
  tags: ["websocket", "memory-leak", "bug-fix", "resolved"]
});

`delete_context(id: string): Promise<boolean>`

通过ID删除上下文。

`cleanup_empty_projects(options?: CleanupOptions): Promise<CleanupResult>`

清理没有任何记忆的空项目记录。

参数:

dry_run (boolean) - 仅预览将被删除的项目，不实际删除 (默认: true)

返回: 清理结果对象

示例:

// 预览将被删除的空项目
const preview = await cleanup_empty_projects({ dry_run: true });
console.log(`将删除 ${preview.deleted_count} 个空项目`);

// 实际删除空项目
const result = await cleanup_empty_projects({ dry_run: false });
console.log(`已删除 ${result.deleted_count} 个空项目`);

实用方法

`cleanup(): Promise<void>`

执行数据库清理和优化。

`stats(): Promise<DatabaseStats>`

获取数据库统计信息和健康状态。

`export(format: 'json' | 'csv'): Promise<string>`

将所有上下文导出为指定格式。

使用场景

软件开发

跟踪实现决策和技术选择
跨开发会话维护上下文
存储和检索代码模式与片段
记录架构决策及其原因

研究与学习

从多个来源积累知识
建立相关概念之间的联系
在数周或数月内维护研究上下文
创建可搜索的个人知识库

项目管理

跟踪项目演进和关键决策
跨团队会议维护上下文
存储项目相关的见解和经验
记录事后总结和回顾

AI助手增强

为AI对话提供持久记忆
基于历史启用上下文感知响应
维护用户偏好和项目细节
支持与AI的长期关系建立

开发指南

环境设置

# 克隆仓库
git clone https://github.com/JochenYang/Devmind.git
cd Devmind

# 安装依赖
npm install

# 开发模式(带监听)
npm run dev

# 运行测试
npm test

# 类型检查
npm run type-check

# 代码检查
npm run lint

🤝 贡献指南

我们欢迎为DevMind MCP做出贡献!请遵循以下步骤:

开发流程

Fork 仓库
创建功能分支: git checkout -b feature/amazing-feature
提交更改: git commit -m 'Add amazing feature'
推送到分支: git push origin feature/amazing-feature
打开 Pull Request

代码标准

遵循TypeScript最佳实践
维持80%以上的测试覆盖率
使用约定式提交消息
为所有公共API编写文档
为新功能添加测试

📄 许可证

本项目采用MIT许可证。详情请参阅LICENSE文件。

🔗 支持

问题反馈: GitHub Issues
讨论交流: GitHub Discussions
NPM包: devmind-mcp

DevMind MCP - 为AI助手打造的智能上下文感知记忆系统

Made with ❤️ by Jochen

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

DevMind MCP

为什么选择 DevMind MCP?

目录

概览

什么是 DevMind MCP?

核心特性

主要功能

技术特性

架构设计

📍 项目结构

步骤 2: 重启 MCP 客户端

步骤 3: 尝试第一个命令

下一步

AI 如何使用 DevMind

使用指南

MCP工具速查

代码库索引

项目管理

会话管理

上下文操作

搜索与发现

可视化

ContextEngine (v2.4.9 新功能)

核心特性

工作原理

默认排除项

使用示例

与语义搜索的集成

使用示例

存储上下文信息

搜索和检索

更新现有上下文

上下文化搜索

配置设置

基础配置（可选）

配置选项

推荐的系统提示词配置

完整MCP配置示例

API参考

核心方法

record_context(context: ContextData): Promise<string>

semantic_search(query: SearchQuery): Promise<Context[]>

update_context(id: string, updates: Partial<ContextData>): Promise<boolean>

delete_context(id: string): Promise<boolean>

cleanup_empty_projects(options?: CleanupOptions): Promise<CleanupResult>

实用方法

cleanup(): Promise<void>

stats(): Promise<DatabaseStats>

export(format: 'json' | 'csv'): Promise<string>

使用场景

软件开发

研究与学习

项目管理

AI助手增强

开发指南

环境设置

🤝 贡献指南

开发流程

代码标准

📄 许可证

🔗 支持

`record_context(context: ContextData): Promise<string>`

`semantic_search(query: SearchQuery): Promise<Context[]>`

`update_context(id: string, updates: Partial<ContextData>): Promise<boolean>`

`delete_context(id: string): Promise<boolean>`

`cleanup_empty_projects(options?: CleanupOptions): Promise<CleanupResult>`

`cleanup(): Promise<void>`

`stats(): Promise<DatabaseStats>`

`export(format: 'json' | 'csv'): Promise<string>`