# trae-mem

**Repository Path**: iyitong/trae-mem

## Basic Information

- **Project Name**: trae-mem
- **Description**: trae-mem 是一个为 TRAE 设计的跨会话持久化记忆系统，通过 MCP Server 自动记录 AI 的工具调用并压缩为结构化知识，在每次新会话开始时注入历史上下文，让 AI 具备连续记忆能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# trae-mem

> **TRAE 的跨会话记忆系统** — 让 AI 在每次会话中都能"记住"之前做过什么。

[快速开始](#-快速开始) · [MCP 工具](#-mcp-工具) · [配置](#-配置)

***

## ✨ 特性

- 🧠 **自动记忆注入** — 新会话自动加载项目历史上下文
- 📝 **操作自动记录** — Edit/Write/RunCommand 后自动持久化
- 🔍 **全文搜索** — SQLite FTS5，支持中文 n-gram 回退
- 📊 **可视化仪表盘** — React 19 + Vite 构建的 Web UI
- 🤖 **可选 AI 压缩** — Ollama / OpenAI / Anthropic 提升记忆质量
- 🔌 **MCP 协议** — 14 个工具，与 TRAE 深度集成
- 🔒 **隐私保护** — 敏感数据自动过滤，文件路径自动脱敏
- 🔄 **SSE 实时推送** — 记忆变更即时同步到 Web UI

## 🚀 快速开始

### 方式一：AI 一键安装（推荐）

在 TRAE 中直接告诉 AI：

> "帮我从 https://gitee.com/iyitong/trae-mem 安装 trae-mem"

AI 会自动读取仓库中的 [`SKILL.md`](SKILL.md) 并按其指引逐步完成安装，每步完成后都会告知你当前进度和下一步操作。

> 安装完成后，新建会话对 AI 说"查看 trae-mem 状态"即可验证。需要 Web UI 时说"启动 trae-mem 控制面板"。

### 方式二：手动安装

```bash
# 前置要求：Node.js >= 18、pnpm 9.x（npm install -g pnpm@9）
git clone https://gitee.com/iyitong/trae-mem.git ~/.trae-mem
cd ~/.trae-mem && pnpm install && pnpm build
node dist/cli/trae-mem.js init
```

然后按 [`SKILL.md`](SKILL.md) 中步骤 3-5 配置 MCP Server、添加用户规则、重启 IDE 并验证安装。

## 🛠 MCP 工具

| 工具                       | 用途      | 调用时机                        |
| ------------------------ | ------- | --------------------------- |
| `trae_mem_context`       | 获取历史上下文 | 新会话开始时（必须）                  |
| `trae_mem_record`        | 记录操作    | Edit/Write/RunCommand 后（必须） |
| `trae_mem_search`        | 搜索历史    | 需要回顾时                       |
| `trae_mem_decision`      | 记录结构化决策 | 做出重要架构/设计决策时                |
| `trae_mem_pin`           | 固定重要信息  | 遇到重要观察或决策时                  |
| `trae_mem_report`        | 生成项目报告  | 需要活动摘要时                     |
| `trae_mem_related_files` | 分析关联文件  | 修改文件时了解影响范围                 |
| `trae_mem_timeline`      | 查看时间线   | 按时间顺序回溯操作                   |
| `trae_mem_summarize`     | 生成会话摘要  | 需要特定会话摘要时                   |
| `trae_mem_stats`         | 查看统计    | 需要使用统计时                     |
| `trae_mem_toggle`        | 开关记录    | 处理敏感数据前关闭，完成后开启             |
| `trae_mem_delete`        | 删除记录    | 清理不需要的观察/会话/项目数据           |
| `trae_mem_update`        | 更新记录    | 修正观察的标题/叙述/类型等信息           |

> 关闭记录后 `trae_mem_record` 会被静默跳过，用户规则保持生效，重新开启后自动恢复。

## 💻 CLI 命令

```bash
trae-mem init                          # 初始化数据库
trae-mem worker start [--port 8080]    # 启动服务
trae-mem worker stop                   # 停止服务
trae-mem worker status                 # 查看状态
trae-mem context --project "my-app"    # 获取项目上下文
trae-mem search "关键词" [--project] [--type bugfix] [--limit 10]
trae-mem timeline --anchor 42           # 查看时间线
trae-mem summary --session "abc"        # 生成会话摘要
trae-mem stats [--json]                 # 查看统计
trae-mem export backup.json             # 导出数据
trae-mem import backup.json             # 导入数据
trae-mem config [--set key=value]       # 管理配置
trae-mem clean --project "my-app"       # 清理数据
trae-mem update                         # 在线更新
```

## ⚙️ 配置

三级优先级：**环境变量 > 配置文件 > 默认值**（配置文件：`~/.trae-mem/config.json`）

| 环境变量                      | 默认值           | 说明                               |
| ------------------------- | ------------- | -------------------------------- |
| `TRAE_MEM_DATA_DIR`       | `~/.trae-mem` | 数据目录                             |
| `TRAE_MEM_WORKER_PORT`    | `37778`       | 服务端口                             |
| `TRAE_MEM_LANGUAGE`       | `zh`          | 输出语言                             |
| `TRAE_MEM_LOG_LEVEL`      | `info`        | 日志级别                             |
| `TRAE_MEM_API_TOKEN`      | _(无)_         | API Bearer Token                 |
| `TRAE_MEM_READONLY`       | `false`       | 只读模式                             |
| `TRAE_MEM_AUTO_SUMMARIZE` | `true`        | 空闲时自动生成会话摘要                      |
| `TRAE_MEM_AI_ENABLED`     | `false`       | 启用 AI 压缩                         |
| `TRAE_MEM_AI_PROVIDER`    | `ollama`      | AI 提供商 (ollama/openai/anthropic) |
| `TRAE_MEM_AI_MODEL`       | `qwen2.5:3b`  | AI 模型                            |
| `TRAE_MEM_AI_API_KEY`     | _(无)_         | API 密钥                           |

## 🤖 AI 压缩（可选）

默认使用规则压缩器（零外部依赖）。开启 AI 压缩可显著提升记忆质量：

```bash
ollama pull qwen2.5:3b                    # Ollama（免费本地）
TRAE_MEM_AI_ENABLED=true node dist/cli/trae-mem.js worker start       # 启动

# 或使用 OpenAI
TRAE_MEM_AI_ENABLED=true TRAE_MEM_AI_PROVIDER=openai \
TRAE_MEM_AI_MODEL=gpt-4o-mini TRAE_MEM_AI_API_KEY=sk-xxx \
node dist/cli/trae-mem.js worker start
```

> AI 压缩失败时自动回退到规则压缩器，不会丢失数据。

## 🏗 架构

```
AI 会话
  ├── trae_mem_record（工具调用 → 观察队列）
  └── trae_mem_context（新会话注入记忆，Token 预算控制）
            │
            ▼
     MemoryWorker（轮询队列 + 压缩 + 重试）
            │
            ├── RuleBasedCompressor（默认，零依赖）
            └── AICompressor（可选，Ollama/OpenAI/Anthropic）
            │
            ▼
     SQLite + FTS5
            │
            ▼
     HTTP 服务（REST API + SSE + Web UI）
```

## 📁 项目结构

```
trae-mem/
├── src/
│   ├── cli/trae-mem.ts          # CLI 入口
│   ├── config.ts                # 配置管理
│   ├── types/index.ts           # 类型定义
│   ├── store/                   # 数据层（SQLite + 迁移 + CRUD）
│   ├── search/                  # 搜索（FTS5 + CJK 回退）
│   ├── processor/               # 压缩器（规则 + AI）+ Worker
│   ├── middleware/              # 工具捕获 + 记忆注入
│   ├── service/worker-service.ts # HTTP API
│   ├── mcp/server.ts            # MCP Server
│   ├── export/backup.ts         # 导入导出
│   ├── viewer/                  # Web UI（React 19 + Vite）
│   └── test/                    # 集成测试
├── package.json
└── tsconfig.json
```

## 🔧 故障排除

| 问题                    | 解决方案                                               |
| --------------------- | -------------------------------------------------- |
| 更新代码后 MCP 不生效         | 执行 `pnpm build`，然后**重启 TRAE IDE**                  |
| MCP Server 无法启动       | 检查 Node.js 18+、确认路径为绝对路径、`pnpm build` 成功           |
| 记忆没有被记录               | 确认用户规则已添加、检查 `<private>` 标签、查看 `~/.trae-mem/logs/` |
| 搜索结果不准确               | 中文自动回退 LIKE 匹配，尝试更精确的关键词                           |
| AI 压缩不工作              | 确认 `TRAE_MEM_AI_ENABLED=true`、Ollama 运行中、模型已下载     |
| `better-sqlite3` 构建失败 | 确保安装了 Python 3 和编译工具                               |

## 📄 许可证

[MIT License](LICENSE) © 2025 trae-mem contributors

## 🤝 贡献

欢迎贡献！请阅读 [贡献指南](CONTRIBUTING.md) 了解如何参与开发。

## 📰 更新日志

查看 [CHANGELOG.md](CHANGELOG.md) 了解完整版本变更记录。