# 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-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Memory MCP Server

> 基于 Model Context Protocol 的 AI 记忆管理服务

## 🌐 项目概述

AI Memory MCP 是一个基于 SQLite 的 Model Context Protocol (MCP) 服务，为 AI 助手提供持久化记忆能力，支持会话摘要的存储、检索和管理。

### ✨ 核心功能

| 功能 | 描述 |
|------|------|
| 📝 **会话摘要管理** | 存储、更新、检索任务会话摘要 |
| 🔍 **多模式搜索** | 支持关键词搜索、FTS5 全文检索、向量语义检索 |
| 📊 **向量检索增强** | 基于 Sentence-Transformers 的 RAG 检索 |
| 🗂️ **多项目管理** | 支持按项目和分支组织记忆 |
| 🎯 **关键决策记录** | 记录重要技术决策及其理由 |
| 📈 **项目周报** | 自动生成周度工作总结报告 |
| 🔄 **会话上下文恢复** | 自动加载最近进行中的任务 |
| 🛠️ **数据库维护** | 定期整理和优化数据库 |
| 📊 **Dashboard 分析面板** | 记忆统计分析、命中率分析、质量评估、优化建议 |

## 📊 Web Dashboard (人类用户管理面板)

Web Dashboard 是一个基于 FastAPI 的可视化管理面板，让人类用户可以直观地管理和分析 AI 记忆数据。

### 启动 Web Dashboard

```bash
# 启动服务（默认端口 8000）
python -m src.web_dashboard.app

# 指定端口
DASHBOARD_PORT=8001 python -m src.web_dashboard.app

# 指定绑定地址（允许外部访问）
DASHBOARD_HOST=0.0.0.0 DASHBOARD_PORT=8000 python -m src.web_dashboard.app
```

启动后，在浏览器中访问：`http://127.0.0.1:8000`

### Web Dashboard 功能

| 页面 | 功能描述 |
|------|---------|
| **Overview (概览)** | 记忆总数、状态分布、项目分布、每日趋势图表 |
| **Memories (记忆列表)** | 查看、搜索、筛选所有记忆，支持单条删除和状态筛选 |
| **Analytics (分析)** | 搜索命中率统计（关键词/FTS/向量检索对比）、搜索日志 |
| **Quality (质量评估)** | 评估记忆质量（内容完整性、标签覆盖、决策记录）、优化建议 |
| **Export/Backup (导出/备份)** | 数据导出（JSON/CSV/Markdown）、数据库备份与下载 |

### Web API 接口

| 接口 | 方法 | 功能描述 |
|------|------|---------|
| `/api/statistics` | GET | 获取统计信息 |
| `/api/summaries` | GET | 获取记忆列表（支持分页和筛选） |
| `/api/summary/{session_id}` | GET | 获取单个记忆详情 |
| `/api/quality/{session_id}` | GET | 评估单个记忆质量 |
| `/api/hit-rates` | GET | 获取命中率分析数据 |
| `/api/summary/{session_id}` | DELETE | 删除单个记忆 |
| `/api/summaries/batch` | DELETE | 批量删除记忆 |
| `/api/summaries/batch/status` | PUT | 批量更新记忆状态 |
| `/api/export/{format}` | GET | 导出数据（json/csv/markdown），支持筛选 |
| `/api/backup` | GET | 下载数据库备份文件 |
| `/api/backup/info` | GET | 获取备份列表信息 |

### 记忆质量评分系统

| 维度 | 评估标准 | 权重 |
|------|---------|------|
| **Content (内容完整性)** | 摘要长度、任务标题、下一步计划 | 33% |
| **Tags (标签覆盖)** | 是否有标签、标签数量 | 33% |
| **Decisions (决策记录)** | 是否记录关键决策及理由 | 34% |

评分范围：0-100 分，根据综合得分提供优化建议。

## 🛠️ 技术栈

- **语言**: Python 3.10+
- **数据库**: SQLite 3.x (支持 FTS5 全文搜索)
- **向量存储**: ChromaDB 0.4+
- **Embedding 模型**: Sentence-Transformers (all-MiniLM-L6-v2)
- **MCP SDK**: FastMCP
- **数据验证**: Pydantic 2.0+

## 📦 安装

```bash
# 使用 pip 安装
pip install ai-memory-mcp

# 或从源码安装
git clone <repository-url>
cd mcp__ai_memory
pip install -e .
```

## 🚀 快速开始

### 启动方式

```bash
# 方式1: 使用命令行工具
ai-memory-mcp

# 方式2: 使用开发模式
mcp dev src/mcp_server/server.py

# 方式3: 使用 HTTP 模式
python -m mcp_server.server --http
```

### 集成到 AI 助手

#### STDIO 模式（默认）

在 MCP 配置中添加：

```json
{
  "mcpServers": {
    "ai_memory": {
      "command": "ai-memory-mcp"
    }
  }
}
```

#### HTTP 模式

当服务以 HTTP 模式运行时（如 Docker 部署），使用 `url` 字段连接：

```json
{
  "mcpServers": {
    "ai_memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

**注意**：服务默认使用 Streamable HTTP transport，端点路径为 `/sse`。启用 `stateless_http` 模式（默认已开启），无需会话管理，适合远程部署。

## 🧰 工具列表

### 核心工具

| 工具名称 | 功能描述 | 必填参数 | 注解 |
|---------|---------|---------|------|
| `memory_save_summary` | 保存任务会话摘要 | session_id, task_title, summary_content, file_paths, project_name | 写操作 |
| `memory_update_summary` | 更新摘要状态或内容 | session_id | 写操作、幂等 |
| `memory_search_summaries` | 多模式降级搜索摘要 | 无（自动三级降级：语义→全文→模糊） | 只读、幂等 |
| `memory_get_summary` | 获取单条摘要详情 | session_id | 只读、幂等 |
| `memory_list_recent` | 列出最近会话 | 无 | 只读、幂等 |
| `memory_add_decision` | 添加关键决策记录 | session_id, description | 写操作 |
| `memory_init_session` | 初始化会话上下文 | 无 | 只读 |
| `memory_weekly_review` | 生成项目周报 | 无 | 只读 |
| `memory_maintenance` | 数据库维护 | 无 | 写操作、破坏性 |
| `memory_export_data` | 导出记忆数据（JSON/CSV/Markdown） | 无 | 只读、幂等 |
| `memory_backup_database` | 创建数据库完整备份 | 无 | 写操作 |

### 工具注解说明

| 注解 | 含义 |
|------|------|
| `readOnlyHint` | 工具是否只读（不修改数据） |
| `destructiveHint` | 工具是否可能破坏数据 |
| `idempotentHint` | 重复调用是否有相同效果 |
| `openWorldHint` | 是否与外部实体交互 |

### 错误响应说明

所有工具的错误响应均面向 AI 模型设计，采用统一格式，包含修正指引和重试提示：

```
【错误】具体错误描述
请修正后重新调用 {工具名} 重试。
💡 提示: 正确格式示例...
```

模型收到此类响应后应自动修正参数并重新调用，无需用户介入。常见错误类型包括：
- **参数校验错误**: 必填参数为空或格式不正确
- **状态值错误**: 使用了无效的任务状态值
- **资源不存在**: session_id 不存在等
- **执行异常**: 数据库或向量存储异常

## 📚 资源 (Resources)

资源提供只读数据访问，类似于 REST API 的 GET 端点。

| 资源 URI | 功能描述 |
|---------|---------|
| `memory://schema` | 返回数据库表结构文档 |
| `memory://stats` | 返回记忆库统计信息 |

### 使用示例

```
GET memory://schema
GET memory://stats
```

## 📋 提示模板 (Prompts)

提示模板提供可复用的交互模式。

| 提示名称 | 功能描述 |
|---------|---------|
| `memory_review_session` | 生成会话复盘提示词 |
| `memory_continue_task` | 生成继续任务提示词 |
| `memory_project_summary` | 生成项目摘要提示词 |

## 🔧 API 详细说明

### 1. memory_save_summary

保存新的任务会话摘要。用于在任务完成或达到里程碑时记录会话信息。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `session_id` | str | 是 | - | 会话唯一标识，建议格式 `session-{YYYYMMDD}-{task_slug}` |
| `task_title` | str | 是 | - | 任务标题，简洁描述任务内容 |
| `summary_content` | str | 是 | - | 完整的 Markdown 摘要内容（仅正文，不要混入下一步计划或文件路径） |
| `file_paths` | str | **是** | - | 修改或新增的文件路径，逗号分隔 |
| `project_name` | str | **是** | - | 项目名称 |
| `status` | str | 否 | `completed` | 任务状态，见下方状态值说明 |
| `next_steps` | str | 否 | - | 下一步计划（任务未完全结束时务必填写） |
| `tags` | str | 否 | - | 逗号分隔的标签列表，建议 2-4 个且多样化（如 `auth,jwt,安全`），避免单一标签 |
| `module` | str | 否 | - | 涉及的模块名 |
| `branch_name` | str | 否 | - | 分支名称 |

**允许的状态值**:
- `completed` - 已完成
- `in_progress` - 进行中
- `blocked` - 阻塞中
- `abandoned` - 已放弃
- `pending` - 待处理

**响应**:
```
✓ 摘要保存成功
```
或
```
✗ 保存失败: 错误原因
```

### 2. memory_update_summary

更新已有摘要的状态或内容。用于更新任务进度或修改摘要信息。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `session_id` | str | 是 | - | 要更新的会话唯一标识 |
| `new_status` | str | 否 | - | 新的任务状态（允许值同上） |
| `updated_content` | str | 否 | - | 更新后的摘要内容 |

**注意**: `new_status` 和 `updated_content` 至少需提供其一。

**响应**:
```
✓ 摘要更新成功
```
或
```
✗ 更新失败: 错误原因
```

### 3. memory_search_summaries

搜索会话摘要，支持多种搜索模式。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | str | 否 | - | 搜索关键词 |
| `tags` | str | 否 | - | 标签筛选 |
| `module` | str | 否 | - | 模块筛选 |
| `status` | str | 否 | - | 状态筛选 |
| `project_name` | str | 否 | - | 项目名称筛选 |
| `branch_name` | str | 否 | - | 分支名称筛选 |
| `limit` | int | 否 | `10` | 返回结果数量限制 |

**搜索模式说明**（无需手动选择，内部自动三级降级）:

| 降级优先级 | 模式 | 说明 |
|-----------|------|------|
| 1（优先） | 向量语义检索 | Sentence-Transformers 语义匹配，结果排在最前 |
| 2（降级） | FTS5 全文检索 | SQLite FTS5 索引精确匹配，补充语义检索遗漏的结果 |
| 3（兜底） | LIKE 模糊匹配 | 基础字符串模糊匹配，最大限度召回 |
| — | 结果合并 | 按优先级去重合并，向量匹配结果优先展示 |

**响应示例**:
```
找到 3 条摘要：

------------------------------------------------------------

## 实现用户登录功能
**Session ID**: `session-20240101-user-login`
**Status**: completed
...
```

### 4. memory_get_summary

根据 session_id 获取单条完整摘要的详细信息。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `session_id` | str | 是 | - | 会话唯一标识 |

**响应**:
```markdown
## 任务标题
**Session ID**: `session-xxx`
**Status**: completed
**Created**: 2024-01-01 10:00:00
**Tags**: 前端,登录

### Summary
摘要内容...

### Next Steps
下一步计划...
```

### 5. memory_list_recent

列出最近的会话摘要。默认按创建时间倒序返回。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `limit` | int | 否 | `10` | 返回数量限制 |
| `project_name` | str | 否 | - | 项目名称筛选 |
| `branch_name` | str | 否 | - | 分支名称筛选 |

**响应**:
```
最近 5 条会话：

1. **实现用户登录功能**
   - Session: `session-20240101-user-login`
   - Status: completed
   - Created: 2024-01-01 10:00:00
   - Tags: 前端,登录
```

### 6. memory_add_decision

向指定会话添加关键决策记录。用于记录重要的技术决策及其理由。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `session_id` | str | 是 | - | 会话唯一标识 |
| `decision_type` | str | 是 | - | 决策类型，如 `架构选型`、`技术方案`、`优先级调整` |
| `description` | str | 是 | - | 决策描述 |
| `reasoning` | str | 否 | - | 决策理由 |

**响应**:
```
✓ 决策添加成功
```

### 7. memory_init_session

初始化会话上下文。检索最近进行中的任务，帮助恢复之前的上下文。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `project_name` | str | 否 | - | 项目名称筛选 |
| `branch_name` | str | 否 | - | 分支名称筛选 |

**响应示例**:
```
📋 最近进行中的任务：

1. **实现用户登录功能**
   - Session: `session-20240101-user-login`
   - Next Steps: 完成密码重置功能

💡 要继续处理这些任务中的哪一个？
```

### 8. memory_weekly_review

生成项目周报。自动汇总本周完成的任务、关键决策和风险提示。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `project_name` | str | 否 | - | 项目名称筛选 |
| `branch_name` | str | 否 | - | 分支名称筛选 |

**响应示例**:
```markdown
# 📊 项目周报 (2024-01-01 ~ 2024-01-07)

## ✅ 本周完成的功能
- **实现用户登录功能**
  - 📁 src/auth/login.py

## 🎯 关键决策
- **技术方案**: 使用 JWT 替代 Session
  - 💭 JWT 无状态，更适合分布式部署

## ⚠️ 风险提示
- 无

## 📌 下一步建议
- 用户登录功能: 完成密码重置功能
```

### 9. memory_maintenance

执行数据库维护操作。包括 FTS 索引重建、数据库 VACUUM 整理、向量索引优化。

**参数**: 无

**响应**:
```
✓ 数据库维护完成
- FTS 索引已重建
- 数据库已 VACUUM
- 向量索引已优化
```

### 10. memory_export_data

导出记忆数据，支持 JSON、CSV、Markdown 三种格式。支持按项目、分支、状态、日期范围筛选。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `export_format` | str | 否 | `json` | 导出格式：`json` / `csv` / `markdown` |
| `project_name` | str | 否 | - | 项目名称筛选 |
| `branch_name` | str | 否 | - | 分支名称筛选 |
| `status` | str | 否 | - | 状态筛选 |
| `after_date` | str | 否 | - | 起始日期，如 `2024-01-01` |
| `before_date` | str | 否 | - | 截止日期，如 `2024-12-31` |
| `limit` | int | 否 | `0` | 最大导出条数，`0` 表示不限制 |

**响应**:
```
✅ 导出成功 (JSON)
[...导出数据...]
```

### 11. memory_backup_database

创建 SQLite 数据库文件的完整离线备份。备份文件默认保存在 `~/.ai-memory/backups/` 目录下，文件名包含时间戳。

**参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `backup_path` | str | 否 | - | 自定义备份文件保存路径，不指定则自动生成 |

**响应**:
```
✅ 数据库备份成功
备份文件路径: /home/user/.ai-memory/backups/ai_memory_backup_20240101_120000.db
```

## 🗄️ 数据库设计

### 表结构

#### session_summaries
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 自增主键 |
| session_id | TEXT | 会话唯一标识（唯一） |
| timestamp | DATETIME | 创建时间戳 |
| task_title | TEXT | 任务标题 |
| status | TEXT | 状态（五选一约束） |
| summary_content | TEXT | 摘要内容 |
| next_steps | TEXT | 下一步计划 |
| tags | TEXT | 标签 |
| module | TEXT | 模块名 |
| file_paths | TEXT | 文件路径 |
| project_name | TEXT | 项目名称 |
| branch_name | TEXT | 分支名称 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

#### key_decisions
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 自增主键 |
| session_id | TEXT | 会话 ID |
| decision_type | TEXT | 决策类型 |
| description | TEXT | 决策描述 |
| reasoning | TEXT | 决策理由 |

### 索引

- `idx_session_summaries_tags`
- `idx_session_summaries_module`
- `idx_session_summaries_status`
- `idx_session_summaries_project`
- `idx_session_summaries_branch`

## ⚙️ 配置

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `AI_MEMORY_DB_PATH` | ~/.ai-memory/ai_memory.db | 数据库文件路径 |
| `AI_MEMORY_MODEL_PATH` | ~/.ai-memory/models | 模型缓存目录 |
| `AI_MEMORY_HOST` | 127.0.0.1 | HTTP 绑定地址 |
| `AI_MEMORY_PORT` | 8000 | HTTP 端口 |

### 配置文件

在 `~/.ai-memory/.env` 中配置：

```env
AI_MEMORY_DB_PATH=/path/to/ai_memory.db
AI_MEMORY_MODEL_PATH=/path/to/models
```

## 🧪 测试

```bash
# 运行所有测试
pytest tests/

# 运行单元测试
pytest tests/unit/

# 运行集成测试
pytest tests/integration/
```

## 📊 评估

项目包含评估测试用例，用于验证 MCP 工具的有效性：

```bash
# 运行评估
mcp eval evaluations.xml
```

## 📝 版本历史

| 版本 | 更新内容 |
|------|---------|
| **v1.5.0** | 数据导出与备份 - 导出 JSON/CSV/Markdown，数据库离线备份，Dashboard 导出管理界面 |
| **v1.4.0** | 产品化升级 - 标准化工具定义、添加 Resources 和 Prompts 支持、创建评估文件 |
| **v1.3.0** | 代码全面优化 - 类型注解、连接管理、统一响应格式 |
| **v1.2.0** | 向量检索增强 (RAG)、会话初始化、周报生成 |
| **v1.1.0** | 多项目管理、FTS5 全文检索、数据库维护 |
| **v1.0.0** | 初始版本，核心 CRUD 功能 |

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License