# DevMemory

轻量级 MCP Server，为 AI 编程助手提供跨会话持久记忆能力。

AI 助手（Cursor、Kiro、Claude Code 等）每次新会话都会"失忆"。DevMemory 通过 MCP 协议为 AI 提供持久化记忆存储，让它记住你的项目知识、踩坑记录、开发决策，跨会话延续上下文。

## 工作原理

```
AI 助手 ←→ MCP 协议 ←→ DevMemory Server ←→ SQLite + sqlite-vec
```

- 所有记忆存储在本地 `~/.devmemory/memory.db`，通过 `project_dir` 字段隔离不同项目
- 使用 ONNX Runtime 在本地运行 Embedding 模型（`intfloat/multilingual-e5-small`），无需 API Key
- 向量语义搜索：即使用词不同，也能找到相关记忆
- 自动去重：余弦相似度 > 0.95 时更新已有记忆，不会重复存储

## 快速开始

### 方式一：pip 安装（推荐）

```bash
# 1. 安装
pip install aivectormemory

# 2. 进入你的项目目录
cd /path/to/your/project

# 3. 一键配置 MCP（交互式选择 IDE 和启动方式）
run install

# 4. 重启 IDE，完成
```

### 方式二：uvx 运行（无需安装）

```bash
# 1. 进入你的项目目录
cd /path/to/your/project

# 2. 一键配置（选择 uvx 启动方式）
uvx aivectormemory install

# 3. 重启 IDE，完成
```

### 方式三：手动配置

在 IDE 的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "devmemory": {
      "command": "run",
      "args": ["--project-dir", "/path/to/your/project"]
    }
  }
}
```

各 IDE 配置文件位置：

| IDE | 配置文件路径 |
|-----|------------|
| Kiro | `.kiro/settings/mcp.json` |
| Cursor | `.cursor/mcp.json` |
| Claude Code | `.mcp.json`（项目根目录） |
| Windsurf | `.windsurf/mcp.json` |
| VSCode | `.vscode/mcp.json` |
| Trae | `.trae/mcp.json` |
| OpenCode | `opencode.json`（项目根目录） |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） |

## 换项目

每个项目需要独立配置，切换项目时：

```bash
cd /path/to/new/project
run install
```

## 工具详解

DevMemory 提供 7 个 MCP 工具，AI 助手会自动调用。

### remember — 存入记忆

```
参数：
  content (string, 必填)  记忆内容，支持 Markdown
  tags    (string[], 必填) 标签列表，如 ["踩坑", "python"]
  scope   (string)        "project"（默认）或 "user"（跨项目）
```

存入一条记忆。如果已存在相似度 > 0.95 的记忆，会更新而非重复创建。

示例场景：AI 发现一个框架的坑，调用 `remember` 记录下来，下次遇到同类问题时能回忆起来。

### recall — 语义搜索记忆

```
参数：
  query   (string)        搜索关键词（语义搜索，与 tags 二选一）
  tags    (string[])      按标签精确过滤（无 query 时走纯标签查询）
  scope   (string)        "project" / "user" / "all"（默认）
  top_k   (integer)       返回数量，默认 5
```

通过向量相似度搜索记忆。比如搜"数据库连接超时"，能找到之前记录的"MySQL 连接池配置踩坑"。

也支持纯标签查询：只传 `tags: ["项目知识"]` 可以拉取该标签下所有记忆。

### forget — 删除记忆

```
参数：
  memory_id  (string)     单个记忆 ID
  memory_ids (string[])   批量删除多个 ID
```

### status — 会话状态管理

```
参数：
  state (object, 可选)    不传 = 读取当前状态，传 = 部分更新
    is_blocked     (boolean)   是否阻塞
    block_reason   (string)    阻塞原因
    current_task   (string)    当前任务
    next_step      (string)    下一步
    progress       (string[])  进度列表
    recent_changes (string[])  最近修改
    pending        (string[])  待处理事项
```

跨会话保持工作状态。新会话开始时 AI 读取状态，知道上次做到哪了、有没有阻塞、还有什么待处理。

### track — 问题跟踪

```
参数：
  action  (string, 必填)  "create" / "update" / "archive" / "list"
  title   (string)        问题标题（create 时必填）
  issue_id (integer)      问题 ID（update/archive 时必填）
  status  (string)        "pending" / "in_progress" / "completed"
  content (string)        排查内容
  date    (string)        日期 YYYY-MM-DD
```

轻量级问题追踪。AI 在开发过程中发现 bug 或待处理事项时，用 `track create` 记录，修复后 `track archive` 归档。

### digest — 记忆摘要

```
参数：
  scope          (string)   "project"（默认）/ "user" / "all"
  since_sessions (integer)  最近 N 次会话，默认 20
  tags           (string[]) 按标签过滤
```

提取指定范围内的记忆列表，供 AI 归纳总结。

### auto_save — 自动保存会话信息

```
参数：
  decisions     (string[])  本次对话的关键决策
  modifications (string[])  修改的文件和内容摘要
  pitfalls      (string[])  遇到的坑和解决方案
  todos         (string[])  产生的待办事项
  scope         (string)    "project"（默认）/ "user"
  extra_tags    (string[])  额外标签
```

每次对话结束时调用，自动将决策、修改、踩坑、待办分类存储为独立记忆，自动打标签和去重。

## Web 看板

DevMemory 内置一个 Web 管理界面，可以可视化查看和管理所有记忆、会话状态、问题跟踪。

```bash
run web --project-dir /path/to/your/project --port 9080
```

浏览器访问 `http://localhost:9080`。

功能：
- 浏览、搜索、编辑、删除记忆
- 查看会话状态
- 查看问题跟踪记录
- 3D 向量网络可视化

## 配合 Steering 规则使用

DevMemory 本身只是存储层。要让 AI 助手主动使用这些工具，需要在 IDE 的 Steering 规则（系统提示词）中告诉 AI 何时调用。

推荐在项目的 Steering 规则中加入类似指引：

```
# 记忆管理

- 新会话开始时：调用 status 读取会话状态
- 遇到踩坑时：调用 remember 记录，标签加 "踩坑"
- 需要查找历史经验时：调用 recall 搜索
- 对话结束前：调用 auto_save 保存本次对话关键信息
```

不同 IDE 的 Steering 配置方式不同：
- Kiro：`.kiro/steering/*.md`
- Cursor：`.cursor/rules/*.md`
- Claude Code：`CLAUDE.md`

## 中国大陆用户

首次运行会自动下载 Embedding 模型（约 200MB）。如果下载慢，设置 HuggingFace 镜像：

```bash
export HF_ENDPOINT=https://hf-mirror.com
```

或在 MCP 配置中添加 env：

```json
{
  "mcpServers": {
    "devmemory": {
      "command": "run",
      "args": ["--project-dir", "."],
      "env": {
        "HF_ENDPOINT": "https://hf-mirror.com"
      }
    }
  }
}
```

## 数据存储

所有数据存储在 `~/.devmemory/memory.db`（SQLite），包含：
- `memories` — 记忆表（含向量索引）
- `session_state` — 会话状态
- `issues` / `issues_archive` — 问题跟踪

不同项目通过 `project_dir` 字段隔离，共用同一个数据库文件。

## 依赖

- Python >= 3.10
- sqlite-vec >= 0.1.0
- onnxruntime >= 1.16
- tokenizers >= 0.15
- huggingface-hub >= 0.20
- numpy >= 1.24

## License

MIT
