evolve-memory-system/ARCHITECTURE.md

一个集成了LlamaIndex RAG, LMCE和MCP工具的本地记忆系统，专为小说《进化》设计。

# Evolve Memory System - 新架构设计文档

## 系统概述

Evolve Memory System 是一个专为小说创作设计的本地记忆系统，采用全新的架构设计，确保只有一个对外接口（LMCE API Server），而 RAG 作为内部组件提供支持。

## 系统架构

```
[Client/Qwen/MCP Client]
         |
         | MCP Protocol / REST API
         |
[L M C E   A P I   S e r v e r]  <- 唯一对外接口
         |
    ------------- 
    |           |
[RAG Module]  [Memory Management]
    |           |
[Document DB]  [Memory Cache]
```

## 组件说明

### 1. LMCE API Server (唯一对外接口)

LMCE (Local Memory Compression Engine) API Server 是系统的唯一对外接口，提供以下功能：

#### 核心功能：
1. **记忆管理**：添加、获取、搜索、删除记忆
2. **小说设定管理**：创建、读取、更新、删除小说的各种设定
3. **智能搜索**：结合记忆和文档进行智能搜索
4. **设定查询**：专门用于查询小说设定的接口

#### API 端点：

##### 健康检查
- `GET /health` - 系统健康检查

##### 记忆管理
- `POST /memories` - 添加记忆
- `GET /memories/{memory_id}` - 获取记忆
- `GET /memories` - 搜索记忆
- `DELETE /memories/{memory_id}` - 删除记忆
- `DELETE /memories` - 清空所有记忆

##### 小说设定管理
- `GET /settings` - 列出所有设定
- `GET /settings/{category}/{name}` - 获取特定设定
- `POST /settings` - 创建设定
- `PUT /settings/{category}/{name}` - 更新设定
- `DELETE /settings/{category}/{name}` - 删除设定

##### 智能搜索
- `POST /search` - 智能搜索（结合记忆和文档）

##### 设定查询
- `GET /query-setting` - 查询小说设定

### 2. RAG Module (内部组件)

RAG (Retrieval-Augmented Generation) Module 是内部组件，不直接对外暴露：

#### 核心功能：
1. **文档索引**：索引小说设定文档
2. **增量更新**：监控文件变化并实时更新索引
3. **文档查询**：基于向量搜索的文档查询

#### 主要特性：
- **增量索引**：只在文件发生变化时更新相关部分
- **文件监控**：自动监控设定目录的变化
- **轻量级**：基于文件系统存储，无需外部数据库

### 3. Memory Management (内部组件)

Memory Management 是内部组件，负责：

#### 核心功能：
1. **记忆存储**：存储创作过程中产生的临时记忆
2. **记忆压缩**：压缩相似的记忆条目
3. **记忆搜索**：基于关键词的记忆搜索

## 数据流向

### 客户端请求处理流程：
1. 客户端发送请求到 LMCE API Server
2. LMCE API Server 解析请求并分发到相应组件
3. 如果涉及文档查询，调用 RAG Module
4. 如果涉及记忆操作，调用 Memory Management
5. 合并结果并返回给客户端

### 内部组件协作流程：
1. RAG Module 监控文件变化
2. 文件发生变化时，RAG Module 自动更新索引
3. LMCE API Server 请求查询时，调用 RAG Module 获取文档信息
4. Memory Management 存储和管理临时记忆
5. LMCE API Server 综合文档信息和记忆信息返回结果

## 设计原则

### 1. 单一入口原则
- 所有外部请求必须通过 LMCE API Server
- RAG Module 和 Memory Management 不直接对外暴露

### 2. 职责分离原则
- LMCE API Server：对外接口和请求协调
- RAG Module：文档索引和查询
- Memory Management：记忆存储和管理

### 3. 增量处理原则
- 文件变化时进行增量更新而非全量重建
- 内存使用优化，避免不必要的资源消耗

### 4. 实时响应原则
- 文件监控实时感知变化
- 索引更新及时反映最新状态

## 使用示例

### 1. 添加记忆
```bash
curl -X POST http://localhost:8000/memories \
  -H "Content-Type: application/json" \
  -d '{
    "id": "mem_001",
    "content": "主角李明的能力是能够感知他人的情绪变化",
    "importance": 0.8,
    "tags": ["character", "ability"]
  }'
```

### 2. 创建小说设定
```bash
curl -X POST http://localhost:8000/settings \
  -H "Content-Type: application/json" \
  -d '{
    "category": "world",
    "name": "future_world",
    "content": "# 未来世界设定\n\n## 时间背景\n2050年，人工智能高度发达..."
  }'
```

### 3. 智能搜索
```bash
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "主角的能力是什么？",
    "limit": 10
  }'
```

### 4. 查询设定
```bash
curl "http://localhost:8000/query-setting?question=未来世界的科技发展水平如何？"
```

## 部署和维护

### 启动服务
```bash
npx evolve-memory-system@1.0.9 start
```

### 停止服务
```bash
npx evolve-memory-system@1.0.9 stop
```

### 查看状态
```bash
npx evolve-memory-system@1.0.9 status
```

### 重置索引
```bash
npx evolve-memory-system@1.0.9 init-rag --reset
```

## 故障排除

### 常见问题

1. **服务无法启动**：
   - 检查端口是否被占用
   - 查看日志文件 `/tmp/lmce.log`

2. **查询无结果**：
   - 检查文档是否正确索引
   - 重新初始化 RAG 索引

3. **文件监控失效**：
   - 检查文件权限
   - 重启服务以重新启动监控

### 日志文件
- LMCE API Server 日志：`/tmp/lmce.log`
- RAG 初始化日志：`/tmp/rag-llama-init.log`
- MCP Server 日志：`/tmp/mcp.log`

## 未来发展

### 即将实现的功能
1. **记忆持久化**：将内存中的记忆持久化到磁盘
2. **版本控制**：对设定文件进行版本控制
3. **协作功能**：支持多人协作创作
4. **导出功能**：支持将内容导出为不同格式

### 性能优化
1. **索引优化**：优化向量索引以提高查询速度
2. **缓存机制**：引入缓存机制减少重复计算
3. **并发处理**：支持更高并发的请求处理

## 总结

新的 Evolve Memory System 架构设计遵循单一入口原则，确保系统清晰、易于维护和扩展。LMCE API Server 作为唯一的对外接口，整合了 RAG 和 Memory Management 的功能，为创作者提供了一个强大而简洁的创作辅助工具。