# mcp__ai_memory

**Repository Path**: zhan_pu/mcp__ai_memory

## Basic Information

- **Project Name**: mcp__ai_memory
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 记忆管理 MCP 工具

## 项目概述

AI 记忆管理 MCP 工具是一个基于 SQLite 的 Model Context Protocol (MCP) 服务，用于存储和检索 AI 会话摘要，实现从文件系统到结构化数据库的升级。

### 核心功能
- 存储会话摘要到 SQLite 数据库
- 支持多条件组合查询和全文搜索（FTS5）
- 支持向量检索增强（RAG），提升检索精度
- 提供会话摘要的增删改查功能
- 记录关键技术决策
- 支持多项目/多分支管理
- 质量检查机制，确保摘要质量
- 会话初始化提示词注入，提供上下文感知
- 轻量级复盘 Agent，自动生成项目周报
- 数据库维护功能（VACUUM）
- 支持 AI 助手通过 MCP 协议调用

## 技术栈

- **语言**: Python 3.8+
- **数据库**: SQLite (支持 FTS5 全文搜索)
- **向量库**: ChromaDB (用于向量存储)
- **Embedding 模型**: Sentence-Transformers (all-MiniLM-L6-v2)
- **MCP SDK**: FastMCP
- **测试框架**: pytest

## 安装说明

### 1. 克隆项目

```bash
git clone <repository-url>
cd mcp__ai_memory
```

### 2. 创建虚拟环境

```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 创建项目标识文件（必须）

AI 记忆工具通过 `.project_name` 文件识别当前项目，确保跨窗口、跨会话时记忆准确关联。

在**使用记忆功能的项目根目录**下创建 `.project_name` 文件：

```bash
# Windows (PowerShell)
echo "my-project-name" > .project_name

# Linux/Mac
echo "my-project-name" > .project_name
```

**文件格式说明**：
- 单行文本，内容即项目名称
- 去除首尾空格
- 忽略 `#` 开头的注释行
- 推荐格式：小写字母 + 连字符（如 `my-awesome-project`）

**示例**：
```
# 项目名称配置文件
my-ecommerce-platform
```

> **注意**：每个需要使用记忆功能的项目都需要创建此文件。文件不存在时，AI 会提示你创建。

## 部署方式

### 方式一：项目级 MCP 配置（推荐）

**优点**：与项目绑定，便于版本控制和团队协作

1. **创建配置文件**
   在项目根目录下的 `.trae` 目录中创建 `mcp.json` 文件：
   ```json
   {
     "mcpServers": {
       "ai_memory": {
         "command": "python",
         "args": [
           "${workspaceFolder}/src/mcp_server/server.py"
         ],
         "env": {
           "START_MCP_TIMEOUT_MS": "60000",
           "RUN_MCP_TIMEOUT_MS": "60000",
           "AI_MEMORY_DB_PATH": "ai_memory.db"
         }
       }
     }
   }
   ```

2. **启用项目级 MCP**
   - 在 TRAE IDE 中，点击右上角的设置图标
   - 进入设置中心，选择左侧导航栏的 MCP
   - 打开 "启用项目级 MCP" 开关
   - 完成确认

### 方式二：手动添加 MCP Server

**优点**：灵活配置，适用于临时使用

1. **打开 MCP 设置**
   - 在 TRAE IDE 中，点击右上角的设置图标
   - 进入设置中心，选择左侧导航栏的 MCP

2. **手动添加配置**
   - 点击右上角的 "添加 > 手动添加"
   - 在配置窗口中，输入以下 JSON 配置：
     ```json
     {
       "mcpServers": {
         "ai_memory": {
           "command": "python",
           "args": [
             "d:\\IdeaProjects\\mcp__ai_memory\\src\\mcp_server\\server.py"
           ],
           "env": {
             "START_MCP_TIMEOUT_MS": "60000",
             "RUN_MCP_TIMEOUT_MS": "60000"
           }
         }
       }
     }
     ```
   - 点击 "确认" 按钮

### 方式三：全局配置（系统服务）

**优点**：持续运行，响应速度快

1. **安装系统服务**
   - **Windows**：使用 Task Scheduler 创建定时任务
   - **Linux**：使用 systemd 服务
   - **MacOS**：使用 launchd 服务

2. **使用 PM2 管理**
   ```bash
   # 安装 PM2
   npm install -g pm2

   # 启动服务（HTTP 模式）
   pm2 start "python src/mcp_server/server.py --http" --name "ai-memory-mcp"

   # 设置开机自启
   pm2 save
   pm2 startup

   # 查看状态
   pm2 status
   ```

3. **配置为 HTTP 模式**
   在 `mcp.json` 中配置：
   ```json
   {
     "mcpServers": {
       "ai_memory_http": {
         "url": "http://localhost:8000/mcp",
         "headers": {
           "START_MCP_TIMEOUT_MS": "60000",
           "RUN_MCP_TIMEOUT_MS": "60000"
         }
       }
     }
   }
   ```

   **重要注意事项**：
   - URL 必须包含 `/mcp` 路径，这是 FastMCP 默认的 Streamable HTTP 端点
   - 确保 MCP Server 正在运行，并且端口 8000 可以访问
   - 如果遇到 SSE 404 错误，请检查 URL 路径是否正确

## 数据库配置

### 数据库文件位置

- **默认位置**：项目根目录下的 `ai_memory.db`
- **自定义位置**：通过环境变量配置
  ```json
  "env": {
    "AI_MEMORY_DB_PATH": "/path/to/ai_memory.db"
  }
  ```

### 多环境配置

| 环境 | 配置示例 | 说明 |
| :--- | :--- | :--- |
| 开发环境 | `AI_MEMORY_DB_PATH": "ai_memory_dev.db` | 开发测试使用 |
| 测试环境 | `AI_MEMORY_DB_PATH": "ai_memory_test.db` | 自动化测试使用 |
| 生产环境 | `AI_MEMORY_DB_PATH": "ai_memory_prod.db` | 生产环境使用 |

## 快速开始

### 1. 启动 MCP Server

**项目级配置**：TRAE 会自动启动 MCP Server（默认使用 STDIO 模式）

**手动启动**：

- **STDIO 模式**（默认）：
```bash
python src/mcp_server/server.py
```

- **HTTP 模式**（用于全局部署）：
```bash
python src/mcp_server/server.py --http
```

### 2. 验证安装

1. **检查日志**：启动时会显示数据库初始化和工具注册的日志
2. **运行测试**：
   ```bash
   pytest tests/
   ```
3. **验证数据库**：运行数据库验证脚本
   ```bash
   python verify_db.py
   ```

### 3. 使用 Skill

当任务完成时，AI 会自动调用 `summarize-session` Skill 生成摘要并存储到数据库。

## 使用方法

### 存储摘要

AI 会在任务完成时自动调用 `mcp__ai_memory__save_summary` 工具存储摘要。

### 检索摘要

你可以通过以下方式检索摘要：

1. **手动检索**：告诉 AI "请检索所有关于'支付模块'且状态为'进行中'的摘要"
2. **自动建议**：AI 会在新任务开始时自动检索相关摘要
3. **全文检索**：使用 `use_fts=true` 参数进行 FTS5 全文搜索

### 工具列表

| 工具名称 | 功能描述 |
| :--- | :--- |
| `save_summary` | 保存新的任务摘要（支持 project_name, branch_name） |
| `update_summary` | 更新已有摘要的状态或内容 |
| `search_summaries` | 根据关键词、标签、模块、状态、项目、分支等条件检索摘要（支持 FTS5 全文检索） |
| `get_summary_by_id` | 根据 session_id 获取完整摘要 |
| `list_recent_sessions` | 列出最近的 N 个会话摘要（支持项目/分支筛选） |
| `add_decision` | 向某次会话添加一条关键决策记录 |
| `maintenance` | 执行数据库维护操作（VACUUM、整理 FTS 索引） |
| `search_summaries_fts` | 使用 FTS5 进行全文检索 |

## 数据库设计

### 表结构

#### session_summaries 表
- `id`: 自增主键
- `session_id`: 会话唯一标识
- `timestamp`: 时间戳
- `task_title`: 任务标题
- `status`: 任务状态（completed, in_progress, pending, blocked, abandoned）
- `summary_content`: 完整的 Markdown 摘要内容
- `next_steps`: 下一步计划
- `tags`: 逗号分隔的标签
- `module`: 涉及的模块名
- `file_paths`: 修改/新增的文件列表
- `project_name`: 项目名称（新增）
- `branch_name`: 分支名称（新增）
- `created_at`: 创建时间
- `updated_at`: 更新时间

#### key_decisions 表
- `id`: 自增主键
- `session_id`: 会话 ID（外键）
- `decision_type`: 决策类型
- `description`: 决策描述
- `reasoning`: 决策理由

#### summary_fts 表（FTS5 虚拟表）
- 用于全文搜索
- 包含 session_id, task_title, summary_content, tags 字段

### 索引

- `idx_session_summaries_tags`: 加速按标签查询
- `idx_session_summaries_module`: 加速按模块查询
- `idx_session_summaries_status`: 加速按状态查询
- `idx_session_summaries_project`: 加速按项目查询（新增）
- `idx_session_summaries_branch`: 加速按分支查询（新增）

## 新功能说明

### 1. 多项目管理

现在支持按项目和分支管理会话摘要：

```python
# 保存带项目信息的摘要
server.save_summary(
    session_id="session-1",
    task_title="任务",
    summary_content="内容",
    project_name="my_project",
    branch_name="feature/new-feature"
)

# 按项目筛选
server.search_summaries(project_name="my_project")

# 按分支筛选
server.list_recent_sessions(project_name="my_project", branch_name="feature/new-feature")
```

### 2. FTS5 全文检索

使用 FTS5 进行更精准的全文搜索：

```python
# 使用 FTS5 全文检索
result = server.search_summaries_fts(query="payment")

# 带筛选条件的 FTS 检索
result = server.search_summaries(
    query="payment",
    project_name="my_project",
    use_fts=True
)
```

### 3. 向量检索增强 (RAG)

使用向量检索提升检索精度：

```python
# 使用向量检索
result = server.search_summaries(
    query="Python web development",
    use_vector=True
)

# 带筛选条件的向量检索
result = server.search_summaries(
    query="数据库优化",
    project_name="my_project",
    use_vector=True
)
```

### 4. 会话初始化提示

自动检索最近的进行中任务并生成提示词：

```python
# 初始化会话
result = server.init_session(project_name="my_project")
prompt = result["prompt"]
# 提示词内容："上次我们有以下进行中的任务：..."
```

### 5. 项目周报生成

自动生成项目周报：

```python
# 生成周报
result = server.weekly_review(project_name="my_project")
report = result["report"]
# 周报包含：本周完成的功能、关键决策、风险提示、下一步建议
```

### 6. 数据库维护

定期执行维护操作整理碎片空间：

```python
# 执行数据库维护
server.maintenance()
# 包括：FTS 索引重建、VACUUM 整理、向量索引优化
```

### 7. 质量检查机制

Skill 现在包含质量检查清单，确保摘要质量：

- [ ] 是否包含了至少一项技术决策及其理由？
- [ ] 是否列出了至少一个具体的文件路径？
- [ ] 下一步计划是否具体可执行？
- [ ] 项目上下文是否已识别？
- [ ] 摘要内容是否足够详细，能够生成有意义的向量 Embedding？

### 8. 项目上下文识别

AI 助手在调用记忆工具前，会自动从当前工作目录向上查找 `.project_name` 文件（最多 2 层），提取项目名称作为上下文标识。同时读取 `.git/HEAD` 获取分支信息。

查找逻辑：
1. 从当前工作目录开始，逐级向上查找 `.project_name` 文件（最多 2 层）
2. 找到后读取第一行有效内容作为 `project_name`
3. 检查同级 `.git` 目录获取 `branch_name`
4. 同一会话内缓存结果，避免重复读取

### 9. 代码优化升级 (v1.3.0)

对 MCP Server 核心代码进行全面重构优化：

**改进要点**：
- 为所有公共方法添加完整的类型注解，提升代码可读性和 IDE 支持
- 引入数据库连接上下文管理器，自动处理连接释放和异常回滚
- 统一错误处理机制，所有工具返回一致的 `{"success": True/False, "message/data": ...}` 格式
- 提取硬编码配置为命名常量，消除魔法数字
- 优化向量检索逻辑，减少不必要的数据获取
- 消除重复 SQL 构建代码，提升可维护性

**API 响应格式统一**：
```
成功响应: {"success": True, "data": <结果>, "message": "<描述>"}
失败响应: {"success": False, "message": "<错误原因>"}
```

**输入验证增强**：
- 所有必填参数在调用前自动验证
- `status` 字段严格限制为五种有效状态
- `session_id`、`task_title`、`summary_content` 等关键字段不能为空

## 测试

运行测试用例：

```bash
pytest tests/
```

## 部署指南

### 本地部署

1. 按照安装说明设置环境
2. 启动 MCP Server
3. 在 AI 工具中注册 MCP Server

### 后台运行

使用 `pm2` 或系统服务将 MCP Server 注册为后台服务：

```bash
# 使用 pm2
pm install -g pm2
pm2 start "python src/mcp_server/server.py" --name "ai-memory-mcp"

# 查看状态
pm2 status

# 停止服务
pm2 stop ai-memory-mcp
```

## 常见问题

### Q: MCP Server 无法启动

A: 检查端口是否被占用，确保依赖包已正确安装。

### Q: 摘要存储失败

A: 检查 session_id 是否唯一，确保数据库文件有写入权限。

### Q: 检索速度慢

A: 确保数据库索引已正确创建，避免使用过于复杂的查询条件。可以使用 FTS5 全文检索提升搜索效率。

### Q: FTS5 全文检索返回空结果

A: FTS5 默认对中文支持有限，建议使用英文进行 FTS5 检索。中文内容可使用普通的 LIKE 查询。

## 版本历史

- **v1.0.0**: 初始版本，实现核心功能
- **v1.1.0**: 新增多项目管理、FTS5 全文检索、质量检查机制、人工确认步骤、数据库维护功能
- **v1.2.0**: 新增向量检索增强 (RAG)、会话初始化提示词注入、轻量级复盘 Agent、向量元数据表
- **v1.3.0**: 代码全面优化升级 - 类型注解、连接管理、统一响应格式、输入验证、常量提取、消除重复代码

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 许可证

MIT License