npm package: @iflow-mcp/fangxh2013-trae-memory
Description: TRAE IDE 智能记忆系统 - 自动记录对话历史、智能上下文管理和任务跟踪
Author: TRAE Community
Latest version: 2.0.0

# 🧠 TRAE Memory - 智能记忆系统

> **TRAE IDE 专用的智能记忆系统，自动记录对话历史、智能上下文管理和任务跟踪**

## ✨ 核心特性

### 🤖 自动记录
- **智能监听**：自动捕获 TRAE Builder 中的用户输入
- **上下文分析**：智能分析对话内容和重要性
- **无感知记录**：后台自动保存，不干扰工作流程

### 📚 记忆管理
- **对话历史**：完整保存用户与助手的对话记录
- **智能检索**：快速查找历史对话和重要信息
- **个性化设置**：保存用户偏好和配置

### 🎯 智能功能
- **上下文恢复**：智能恢复中断的对话上下文
- **任务管理**：跟踪和管理开发任务
- **记忆优化**：自动清理和优化存储空间

## 🚀 快速开始

### 1. 安装依赖
```bash
npm install
```

### 2. 启动服务

#### 方式一：使用管理脚本（推荐）
```bash
# 启动服务
./scripts/server.sh start

# 查看状态
./scripts/server.sh status

# 查看日志
./scripts/server.sh logs

# 停止服务
./scripts/server.sh stop

# 重启服务
./scripts/server.sh restart
```

#### 方式二：直接启动
```bash
node src/servers/index.js
```

### 3. 配置 TRAE IDE

在 TRAE IDE 设置中添加 MCP 服务器配置：

```json
{
  "mcpServers": {
    "trae-memory": {
      "command": "node",
      "args": [
        "/path/to/trae-memory/src/servers/index.js"
      ],
      "cwd": "/path/to/trae-memory",
      "env": {
        "NODE_ENV": "production",
        "AUTO_RECORD": "true",
        "CONTEXT_THRESHOLD": "0.8",
        "TOKEN_ESTIMATION": "true"
      }
    }
  }
}
```

### 4. 重启 TRAE IDE
重启 TRAE IDE 以加载 MCP 服务器配置。

## 📖 详细使用教程

### 基础功能使用

#### 1. 记录输入内容
当你在TRAE Builder中输入内容时，系统会自动记录：
```javascript
// 自动调用
log_input({
  input: "你的输入内容",
  source: "builder", // 或 "chat", "terminal"
  project: "项目名称",
  files: ["相关文件路径"],
  estimatedTokens: 100
})
```

#### 2. 记录对话内容
```javascript
// 记录完整对话
log_chat({
  user_input: "用户问题",
  assistant_response: "助手回复",
  conversation_id: "会话ID",
  metadata: {
    source: "chat",
    project: "项目名称",
    files: ["file1.js", "file2.js"],
    tokens: 150
  }
})
```

#### 3. 获取历史记录
```javascript
// 获取最近5条记录
get_history({ limit: 5 })

// 获取最近10条记录
get_history({ limit: 10 })
```

#### 4. 智能记忆恢复
```javascript
// 根据当前上下文恢复相关记忆
recall({
  query: "React组件优化",
  project: "my-react-app",
  includeCompleted: false,
  limit: 10
})
```

### 高级功能使用

#### 1. Context管理
```javascript
// 检查Context状态
context({ action: "check" })

// 重置Context
context({ action: "reset" })

// 优化Context
context({ 
  action: "optimize",
  tokenCount: 50000,
  maxTokens: 128000
})
```

#### 2. 任务管理
```javascript
// 创建任务
tasks({
  action: "create",
  taskData: {
    title: "实现用户登录功能",
    description: "添加JWT认证和用户验证",
    status: "pending",
    priority: "high",
    project: "web-app",
    tags: ["authentication", "security"]
  }
})

// 更新任务
tasks({
  action: "update",
  taskId: "task_id_here",
  taskData: {
    status: "completed"
  }
})

// 查看任务列表
tasks({
  action: "list",
  filters: {
    status: "pending",
    priority: "high"
  }
})

// 获取任务统计
tasks({ action: "stats" })
```

#### 3. 文件管理
```javascript
// 查看文件状态
files({ action: "status" })

// 清理旧文件（30天前的文件）
files({ 
  action: "clean",
  days: 30
})

// 归档所有数据
files({ action: "archive" })

// 优化文件（只保留最近100条记录）
files({ 
  action: "optimize",
  maxFiles: 100
})
```

#### 4. 设置管理
```javascript
// 保存设置
save_setting({
  key: "theme",
  value: "dark"
})

// 读取设置
get_setting({ key: "theme" })
```

### 服务管理

#### 使用管理脚本
```bash
# 查看帮助
./scripts/server.sh

# 启动服务（后台运行）
./scripts/server.sh start

# 查看详细状态
./scripts/server.sh status

# 实时监控日志
./scripts/server.sh monitor

# 查看最近日志
./scripts/server.sh logs

# 重启服务
./scripts/server.sh restart

# 停止服务
./scripts/server.sh stop
```

#### 日志文件位置
- 服务日志：`logs/server.log`
- PID文件：`.server.pid`

### 数据管理

#### 数据文件结构
```
data/
├── history.json      # 对话历史记录
├── settings.json     # 用户设置
├── context.json      # Context状态
├── tasks.json        # 任务列表
├── session.json      # 会话信息
└── archive/          # 归档文件夹
    ├── backup_2024-10-31.json
    └── history_archive_*.json
```

#### 数据备份与恢复
```bash
# 手动备份
cp -r data/ backup_$(date +%Y%m%d)/

# 使用内置归档功能
# 通过 manage_files({ action: "archive" }) 调用
```

### 故障排除

#### 常见问题

1. **服务无法启动**
   ```bash
   # 检查端口占用
   lsof -i :3000
   
   # 查看详细错误
   ./scripts/server.sh logs
   ```

2. **记录功能不工作**
   ```bash
   # 检查服务状态
   ./scripts/server.sh status
   
   # 重启服务
   ./scripts/server.sh restart
   ```

3. **文件权限问题**
   ```bash
   # 修复权限
   chmod -R 755 data/
   chmod +x scripts/server.sh
   ```

4. **内存使用过高**
   ```javascript
   // 优化文件
   manage_files({ action: "optimize", maxFiles: 50 })
   
   // 清理旧文件
   manage_files({ action: "clean", days: 7 })
   ```

#### 调试模式
```bash
# 启动时显示详细日志
DEBUG=* node src/servers/index.js

# 或使用脚本监控
./scripts/server.sh monitor
```

### 性能优化建议

1. **定期清理数据**
   - 每周运行一次文件清理
   - 设置合理的保留天数（建议30天）

2. **监控文件大小**
   - history.json 超过10MB时进行优化
   - 使用归档功能备份重要数据

3. **合理设置参数**
   - maxFiles: 100-500（根据使用频率）
   - days: 7-30（根据存储需求）

4. **监控系统资源**
   ```bash
   # 查看进程资源使用
   ./scripts/server.sh status
   ```

## 🛠️ 可用工具

### 📝 对话管理
- **`auto_log_input`** - 自动记录 Builder 输入（自动触发）
- **`log_conversation`** - 手动记录对话
- **`get_history`** - 获取历史记录

### 🧠 记忆功能
- **`recover_memory`** - 智能恢复上下文
- **`manage_context`** - 管理上下文信息
- **`manage_tasks`** - 管理任务列表

### ⚙️ 设置管理
- **`save_setting`** - 保存用户设置
- **`get_setting`** - 获取用户设置

## 📁 项目结构

```
trae-memory/
├── src/
│   ├── servers/
│   │   └── index.js          # 主服务器文件
│   ├── config/
│   │   └── timezone.js       # 时区配置
│   └── utils/                # 工具函数
├── data/                     # 数据存储目录
│   ├── history.json         # 对话历史
│   ├── session.json         # 会话信息
│   ├── context.json         # 上下文数据
│   ├── settings.json        # 用户设置
│   └── tasks.json           # 任务列表
├── config/                   # 配置示例
├── scripts/                  # 工具脚本
└── package.json
```

## 🔧 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `NODE_ENV` | `development` | 运行环境 |
| `AUTO_RECORD` | `true` | 是否启用自动记录 |
| `CONTEXT_THRESHOLD` | `0.8` | 上下文重要性阈值 |
| `TOKEN_ESTIMATION` | `true` | 是否启用 Token 估算 |

## 📊 数据格式

### 对话历史 (history.json)
```json
[
  {
    "timestamp": "2024-01-01T12:00:00.000Z",
    "user": "用户输入内容",
    "assistant": "助手回复内容"
  }
]
```

### 用户设置 (settings.json)
```json
{
  "language": "zh-CN",
  "theme": "dark",
  "auto_save": true
}
```

## 🧪 测试和诊断

### 运行测试
```bash
npm test
```

### 诊断连接
```bash
npm run diagnose
```

### 验证核心功能
```bash
npm run verify
```

## 🔍 故障排除

### 1. MCP 服务器无法连接
- 检查 TRAE IDE 中的 MCP 配置
- 确认文件路径正确
- 重启 TRAE IDE

### 2. 自动记录不工作
- 确认 `AUTO_RECORD` 环境变量为 `true`
- 检查 TRAE IDE 是否正确连接到 MCP 服务器
- 查看 TRAE IDE 开发者工具中的错误信息

### 3. 数据文件权限问题
```bash
chmod 755 data/
chmod 644 data/*.json
```

## 📝 更新日志

### v2.0.0 (当前版本)
- 🎯 简化架构，只保留自动版本
- 🚀 优化性能和稳定性
- 📚 完善文档和示例
- 🔧 改进配置和部署流程

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件。

---

**🎉 享受智能记忆带来的便利！**