# 需求文档：DevMemory MCP Server

## 简介

DevMemory 是一个轻量级 MCP Server，为 AI 编程助手提供跨会话持久记忆能力。采用 6 个工具覆盖三大功能：通用记忆（remember/recall/forget）、会话状态（status）、问题跟踪（track）、记忆整理（digest）。

双层存储架构：
- 用户级（`~/.devmemory/`）：个人习惯、编程偏好、通用踩坑记录，跨项目共享
- 项目级（`{project}/.devmemory/`）：项目知识库、技术要点、会话状态、问题跟踪

数据存储：SQLite + sqlite-vec，所有数据（记忆、向量索引、会话状态、问题跟踪）统一存储在 SQLite 数据库中。

技术栈：Python，自实现 MCP 协议（JSON-RPC over stdio），兼容 Kiro IDE 和 opencode。

## 术语表

- **Memory**：一条记忆记录，包含内容、标签、作用域、来源、时间戳和向量嵌入
- **Scope**：记忆作用域，`user`（跟人走，存用户目录）或 `project`（跟项目走，存项目目录）
- **Tag**：自由标签，用于分类和过滤记忆（如 `git`、`习惯`、`php`、`踩坑`）
- **Vector_Index**：SQLite + sqlite-vec 向量索引，存储 Embedding 用于语义搜索
- **Embedding**：文本的向量表示，通过本地模型将文本转换为 384 维浮点数组
- **Session_State**：会话状态记录，存储在项目级 SQLite 数据库的 `session_states` 表中，记录阻塞状态和任务进度
- **Issue**：问题记录，存储在项目级 SQLite 数据库的 `issues` 表中，包含完整生命周期（待处理→进行中→已完成→已归档）
- **Digest**：记忆整理，将多次会话积累的碎片记忆提取出来，由 AI 端归纳总结后写回

## 技术调研结论

### MCP 协议实现

- 自实现 JSON-RPC over stdio，不依赖第三方 MCP 框架
- 核心方法：`initialize`（握手）、`tools/list`（工具列表）、`tools/call`（工具调用）
- 传输协议：stdio（从 stdin 读请求，往 stdout 写响应）
- 启动方式：`python -m devmemory` 或 `uvx devmemory`
- Kiro 配置：`.kiro/settings/mcp.json`
- opencode 配置：`.opencode/mcp.json` 或 `~/.config/opencode/mcp.json`

### sqlite-vec

- PyPI 包：`sqlite-vec`（v0.1.0+）
- 加载方式：`sqlite_vec.load(db)` 需要 `db.enable_load_extension(True)`
- 向量维度：384（匹配 embedding 模型）
- 距离度量：余弦距离（cosine distance），值越小越相似
- macOS：本机 Homebrew Python 3.12.10 已支持 `enable_load_extension`，SQLite 3.49.2，无需额外处理

### Embedding 模型

- 推荐模型：`intfloat/multilingual-e5-small`
  - 维度：384
  - 大小：~118MB
  - 中文支持：优秀（专为多语言设计，100+ 语言）
  - 推理方案：ONNX Runtime（轻量，无需 torch）
  - HuggingFace 已提供 ONNX 格式模型，无需手动转换
  - 需自行实现 tokenize → 推理 → mean pooling → 归一化 流程
- 备选模型：`all-MiniLM-L6-v2`（22MB，中文效果较差）
- 首次加载会自动下载模型到 `~/.cache/huggingface/`
- 国内网络建议配置 HuggingFace 镜像：`export HF_ENDPOINT=https://hf-mirror.com`

### IDE Hook 兼容性

| 能力 | Kiro | opencode |
|------|------|----------|
| 会话结束事件 | `agentStop` hook | `session.idle` plugin event |
| 工具调用前/后 | `preToolUse`/`postToolUse` | `tool.execute.before`/`after` |
| 会话压缩注入 | 不支持 | `session.compacting` hook |
| 自定义工具 | 不支持 | 支持（plugin tool 导出） |

### 竞品分析

| 项目 | 存储 | 向量搜索 | 问题跟踪 | 用户级记忆 | 中文支持 |
|------|------|---------|---------|-----------|---------|
| OpenMemory (CaviraOSS) | SQLite/Postgres | ✅ | ❌ | ❌ | 未知 |
| mcp-mem0 | PostgreSQL + OpenAI | ✅ | ❌ | ❌ | 依赖 API |
| mcp-memory-keeper | 文件 | ❌ | ❌ | ❌ | ❌ |
| mcp-memory (ebailey78) | Markdown + Lunr.js | 关键词 | ❌ | ❌ | 有限 |
| **DevMemory（本项目）** | SQLite | ✅ 本地 | ✅ | ✅ | ✅ |

---

## 需求

### 需求 1：MCP Server 启动与配置

**用户故事：** 作为开发者，我希望 MCP Server 轻量启动，在 Kiro 和 opencode 中都能使用。

#### 验收标准

1. THE Server SHALL 自实现 MCP 协议（JSON-RPC over stdio），不依赖第三方 MCP 框架
2. WHEN 启动时，THE Server SHALL 接受 `--project-dir` 参数指定项目根目录，默认使用当前工作目录
3. WHEN 启动时，THE Server SHALL 自动检测并创建所需目录结构：
   - 用户级：`~/.devmemory/`（memory.db）
   - 项目级：`{project}/.devmemory/`（memory.db）
4. WHEN 启动时，THE Server SHALL 初始化 SQLite 数据库（WAL 模式）和 sqlite-vec 扩展
5. WHEN 启动时，THE Server SHALL 懒加载 Embedding 模型（首次调用 recall 或 remember 时才加载，避免启动延迟）
6. IF sqlite-vec 扩展加载失败，THEN THE Server SHALL 报错退出
7. IF Embedding 模型加载失败，THEN THE Server SHALL 报错退出

### 需求 2：记忆存入（remember）

**用户故事：** 作为 AI 助手，我希望将重要信息存入记忆，以便后续会话中回忆。

#### 验收标准

1. WHEN `remember` 工具被调用时，THE Server SHALL 接受以下参数：
   - `content`（必填）：记忆内容，Markdown 格式文本
   - `tags`（必填）：标签列表，如 `["git", "习惯"]`
   - `scope`（可选）：`user` 或 `project`，默认 `project`
2. WHEN 存入记忆时，THE Server SHALL 自动生成唯一 ID、记录创建时间、计算 Embedding 向量
3. WHEN 存入记忆时，THE Server SHALL 将记忆写入对应 scope 的 SQLite 数据库（memory.db）
4. WHEN 存入记忆时，THE Server SHALL 同步将 Embedding 向量写入 sqlite-vec 虚拟表
5. WHEN 存入成功时，THE Server SHALL 返回 `{id, tags, scope, created_at}`
6. WHEN 存入记忆时，THE Server SHALL 先检查是否存在相似度超过 0.95 的记忆，若存在则更新该记忆而非创建新记录
7. THE Server SHALL 记录每条记忆的 `session_id`（自增会话计数器），用于 digest 功能

### 需求 3：记忆回忆（recall）

**用户故事：** 作为 AI 助手，我希望通过语义搜索找到相关记忆，即使搜索词与原文用词不同。

#### 验收标准

1. WHEN `recall` 工具被调用时，THE Server SHALL 接受以下参数：
   - `query`（必填）：搜索内容
   - `scope`（可选）：`user`、`project` 或 `all`，默认 `all`
   - `tags`（可选）：按标签过滤
   - `top_k`（可选）：返回结果数量，默认 5
2. WHEN scope 为 `all` 时，THE Server SHALL 同时搜索用户级和项目级数据库，合并结果按相似度排序
3. WHEN 向量搜索可用时，THE Server SHALL 将 query 转换为 Embedding，在 sqlite-vec 中执行余弦相似度搜索
4. WHEN 返回结果时，THE Server SHALL 包含 `{id, content, tags, scope, similarity_score, created_at}`
5. IF 没有匹配结果，THEN THE Server SHALL 返回空列表

### 需求 4：记忆删除（forget）

**用户故事：** 作为 AI 助手，我希望删除过时或错误的记忆。

#### 验收标准

1. WHEN `forget` 工具被调用时，THE Server SHALL 接受 `memory_id`（单个 ID）或 `memory_ids`（ID 列表）参数
2. WHEN 删除记忆时，THE Server SHALL 同时删除 SQLite 记录和 sqlite-vec 向量索引
3. WHEN 删除成功时，THE Server SHALL 返回 `{deleted_count, ids}`
4. IF 指定的 ID 不存在，THEN THE Server SHALL 在返回结果中标注哪些 ID 未找到，不影响其他 ID 的删除

### 需求 5：会话状态（status）

**用户故事：** 作为 AI 助手，我希望读取和更新会话状态，以便跨会话保持任务连续性。

#### 验收标准

1. WHEN `status` 工具被调用且未提供 `state` 参数时，THE Server SHALL 从项目级数据库读取当前会话状态，返回结构化数据：`{is_blocked, block_reason, next_step, current_task, progress, recent_changes, pending, updated_at}`
2. WHEN `status` 工具被调用且提供 `state` 参数时，THE Server SHALL 接受以下可选字段进行部分更新：
   - `blocking_status`、`blocking_reason`、`next_step`
   - `current_task`、`progress`（列表）、`recent_changes`（列表）、`pending`（列表）
3. WHEN 更新状态时，THE Server SHALL 仅更新提供的字段，保留未提供字段的原有值
4. WHEN 更新状态时，THE Server SHALL 自动更新 `updated_at` 时间戳
5. IF 数据库中无状态记录，THEN THE Server SHALL 使用默认值创建

### 需求 6：问题跟踪（track）

**用户故事：** 作为 AI 助手，我希望通过统一工具管理问题的完整生命周期。

#### 验收标准

1. WHEN `track` 工具被调用时，THE Server SHALL 接受 `action` 参数，支持以下操作：

**action = "create"**：
2. SHALL 接受 `title`（必填）、`date`（可选，默认当天）
3. SHALL 在数据库中创建新问题记录，状态为 `pending`，自动分配 ID（当日最大编号 + 1）
4. SHALL 返回 `{issue_id, date}`

**action = "update"**：
5. SHALL 接受 `issue_id`（必填）、`date`（可选）、`status`（可选：pending/in_progress/completed）、`content`（可选：追加排查内容）
6. SHALL 更新问题记录的对应字段
7. IF issue_id 不存在，THEN SHALL 返回错误

**action = "migrate"**：
8. SHALL 接受 `source_date`（必填）、`target_date`（可选，默认当天）
9. SHALL 将源日期的 `pending` 和 `in_progress` 问题迁移到目标日期，状态设为 `in_progress`，从 1 重新编号
10. SHALL 将源日期被迁移的问题标记为 `completed`，备注 `→ 已迁移至 YYYY-MM-DD 问题 N`
11. SHALL 返回 `{migrated_count, id_mapping}`

**action = "archive"**：
12. SHALL 接受 `issue_id`（必填）、`content`（必填：完整排查记录）、`date`（可选）
13. SHALL 将问题状态更新为 `archived`，保存完整排查记录到 `archive_content` 字段
14. SHALL 返回 `{issue_id, archived_at}`

**action = "list"**：
15. SHALL 接受 `date`（可选，默认当天）、`status`（可选：过滤状态）
16. SHALL 返回指定日期的问题列表，按编号排序

### 需求 7：记忆整理（digest）

**用户故事：** 作为 AI 助手，我希望定期整理碎片记忆，由 AI 归纳总结后写回精炼版本。

#### 验收标准

1. WHEN `digest` 工具被调用时，THE Server SHALL 接受以下参数：
   - `scope`（可选）：`user`、`project` 或 `all`，默认 `project`
   - `since_sessions`（可选）：最近 N 次会话的记忆，默认 20
   - `tags`（可选）：按标签过滤
2. WHEN 提取记忆时，THE Server SHALL 返回符合条件的所有记忆原始列表，按时间排序
3. WHEN 返回结果时，THE Server SHALL 包含 `{memories: [{id, content, tags, created_at}], total_count, session_range}`
4. THE Server SHALL 不做任何总结或归纳（由 AI 端完成），仅提供原始数据
5. THE Server SHALL 在每次 `initialize` 调用时递增内部 session_id 计数器（每次 IDE 建立新连接视为新会话）

### 需求 8：数据存储

**用户故事：** 作为开发者，我希望数据存储可靠且统一。

#### 验收标准

1. THE Server SHALL 使用 SQLite 存储所有数据，表结构：
   - `memories`：id, content, tags(JSON), scope, session_id, created_at, updated_at
   - `vec_memories`：sqlite-vec 虚拟表，存储 384 维 Embedding 向量
   - `session_state`：id, is_blocked, block_reason, next_step, current_task, progress(JSON), recent_changes(JSON), pending(JSON), updated_at
   - `issues`：id, issue_number, date, title, status(pending/in_progress/completed/archived), content, archive_content, migrated_to, created_at, updated_at
2. `.devmemory/memory.db` SHALL 被添加到 `.gitignore` 建议（可通过 rebuild 重建向量索引）

### 需求 9：错误处理

**用户故事：** 作为 AI 助手，我希望 MCP Server 在异常情况下返回清晰的错误信息。

#### 验收标准

1. IF sqlite-vec 不可用，THEN THE Server SHALL 报错退出
2. IF Embedding 模型不可用，THEN THE Server SHALL 报错退出
3. IF 数据库读写失败，THEN THE Server SHALL 返回包含错误原因的错误信息
4. IF 参数不合法，THEN THE Server SHALL 返回参数校验错误信息
5. THE Server SHALL 所有错误返回统一格式 `{success: false, error: str, details: str}`

### 需求 10：IDE 集成配置

**用户故事：** 作为开发者，我希望在 Kiro 和 opencode 中都能快速配置使用。

#### 验收标准

1. THE Server SHALL 支持以下 Kiro 配置方式（`.kiro/settings/mcp.json`）：
```json
{
  "mcpServers": {
    "devmemory": {
      "command": "uv",
      "args": ["run", "--with", "devmemory", "devmemory", "--project-dir", "."]
    }
  }
}
```
2. THE Server SHALL 支持以下 opencode 配置方式（`.opencode/mcp.json`）：
```json
{
  "mcpServers": {
    "devmemory": {
      "type": "local",
      "command": "uv",
      "args": ["run", "--with", "devmemory", "devmemory", "--project-dir", "."]
    }
  }
}
```
3. THE Server SHALL 支持通过 `pip install devmemory` 或 `uv pip install devmemory` 安装
4. THE Server SHALL 支持通过 `uvx devmemory` 直接运行（无需预安装）

### 需求 11：Web 看板

**用户故事：** 作为开发者，我希望通过浏览器查看和管理 DevMemory 中的数据。

#### 验收标准

1. THE Server SHALL 提供 `devmemory web` 命令启动本地 Web 看板，默认监听 `http://localhost:9080`
2. THE Server SHALL 支持 `--port` 参数自定义端口
3. Web 看板 SHALL 提供以下页面：

**记忆管理**：
4. SHALL 展示记忆列表，支持按关键词搜索、按标签过滤、按 scope 过滤
5. SHALL 支持查看记忆详情（内容、标签、创建时间、所属会话）
6. SHALL 支持删除单条或批量删除记忆
7. SHALL 支持编辑记忆内容和标签

**会话状态**：
8. SHALL 展示当前会话状态（阻塞状态、当前任务、进度、待处理项）
9. SHALL 支持手动修改会话状态各字段

**问题跟踪**：
10. SHALL 展示问题列表，支持按日期和状态过滤
11. SHALL 支持查看问题详情（排查内容、归档记录）
12. SHALL 支持手动切换问题状态

**统计概览**：
13. SHALL 展示基本统计：记忆总数、标签分布、各状态问题数量

**技术实现**：
14. THE Server SHALL 使用内置 HTTP 服务（Python 标准库），不引入额外 Web 框架
15. THE Server SHALL 前端使用纯 HTML + CSS + JavaScript，不引入前端框架
16. THE Server SHALL 复用 MCP Server 的 SQLite 读写逻辑，以只读方式打开数据库（写操作通过独立连接）

---

## 工具速查表

| 工具 | 用途 | 存储层 | 核心参数 |
|------|------|--------|---------|
| `remember` | 存入记忆 | SQLite + 向量 | content, tags, scope |
| `recall` | 语义搜索回忆 | SQLite + 向量 | query, scope, tags, top_k |
| `forget` | 删除记忆 | SQLite + 向量 | memory_id(s) |
| `status` | 会话状态读写 | SQLite | state(可选) |
| `track` | 问题跟踪 | SQLite | action, ... |
| `digest` | 提取待总结记忆 | SQLite | scope, since_sessions |

## 依赖清单

| 包名 | 用途 | 版本要求 |
|------|------|---------|
| `sqlite-vec` | SQLite 向量搜索扩展 | >=0.1.0 |
| `onnxruntime` | 本地模型推理 | >=1.16 |
| `tokenizers` | HuggingFace 分词器 | >=0.15 |
| `huggingface-hub` | 模型下载 | >=0.20 |
| `numpy` | 向量计算 | >=1.24 |

⚠️ macOS 注意：系统自带 Python 3.9.6 不支持 SQLite 扩展加载。本机已安装 Homebrew Python 3.12.10（`/opt/homebrew/Cellar/python@3.12/3.12.10_1/`），SQLite 3.49.2，`enable_load_extension` 可用，sqlite-vec 可直接使用。

## Embedding 模型选择

| 模型 | 维度 | 大小 | 中文支持 | 说明 |
|------|------|------|---------|------|
| `intfloat/multilingual-e5-small` | 384 | ~118MB | ✅ 优秀 | 推荐，100+ 语言 |
| `all-MiniLM-L6-v2` | 384 | ~22MB | ⚠️ 较差 | 备选，英文为主 |

首次使用时模型自动下载到 `~/.cache/huggingface/`，后续离线可用。

## 资源占用预估

| 状态 | 内存 | 说明 |
|------|------|------|
| 空闲（模型未加载） | ~20-30MB | Python 进程 + SQLite |
| 模型已加载 | ~100-200MB | + ONNX Runtime + 模型 |

安装体积：~200MB（onnxruntime ~30MB + 模型 ~118MB + 其他依赖）
