TrulyMEM-TrueHumanMEM/docs/架构.md

# TrulyMEM 架构设计

## 核心原则

- 键盘驱动，零鼠标依赖
- 极简视觉，信息密度优先
- 工具痕迹默认隐藏，需要时可展开
- TUI 与后端分离，多线程通信

## 项目结构

```
TrulyMEM-TrueHumanMEM/
├── trulymem_entry.py    # 入口：先启动 core → 再启动 ui
├── core/               # 后端/业务逻辑
│   ├── __init__.py     # 导出 BackendServer, BackendClient, EmbeddedGraphDB
│   ├── server.py       # BackendServer (多线程队列通信)
│   ├── client.py      # BackendClient
│   ├── embedded_db.py # SQLite 图数据库实现
│   ├── graph_client.py
│   ├── tool_executor.py  # 工具执行器
│   ├── tool_limiter.py  # 工具调用限制器
│   ├── memory_tools.py  # 工具定义
│   ├── prompts/       # 提示词管理
│   │   ├── __init__.py
│   │   ├── prompt_manager.py
│   │   └── templates/
│   │       └── system_prompt.md
│   └── tools/         # 工具模块
│       ├── __init__.py
│       ├── memory_tools.py
│       ├── tool_executor.py
│       └── tool_limiter.py
├── ui/               # TUI 显示层
│   ├── __init__.py    # 导出 GraphMemoryApp, AppConfig
│   ├── app.py         # GraphMemoryApp (纯显示)
│   ├── widgets/      # TUI 组件
│   │   ├── left_panel.py
│   │   ├── right_panel.py
│   │   ├── message_history.py
│   │   ├── message_widget.py
│   │   ├── input_box.py
│   │   ├── config_section.py
│   │   ├── operation_log.py
│   │   ├── cypher_query_box.py
│   │   └── status_bar.py
│   ├── handlers/     # 事件处理
│   │   ├── focus_handler.py
│   │   ├── key_handler.py
│   │   └── message_handler.py
│   ├── models/       # 数据模型
│   │   ├── message.py
│   │   ├── config.py
│   │   └── log_entry.py
│   ├── services/     # 服务层
│   │   ├── config_manager.py
│   │   ├── config_service.py
│   │   └── chat_service.py
│   └── styles/      # 样式文件
│       ├── app.css
│       ├── components.css
│       └── messages.css
└── tests/            # 测试 (38 tests)
```

## 架构图

```
trulymem_entry.py
    │
    ├─ BackendServer.start() → 独立线程运行
    │   ├─ 处理 PROCESS_MESSAGE 请求
    │   ├─ 处理 EXECUTE_TOOL 请求
    │   └─ 管理 GraphMemoryClient, EmbeddedGraphDB
    │
    └─ GraphMemoryApp(backend_server=server)
            │
            └─ BackendClient ← queue.Queue → BackendServer
```

## 组件职责

### core/ (后端)

| 组件 | 职责 |
|------|------|
| `server.py` | 多线程队列通信，处理消息和工具调用 |
| `client.py` | TUI 端的通信客户端 |
| `embedded_db.py` | SQLite 图数据库 CRUD |
| `graph_client.py` | OpenAI/DeepSeek API 客户端 |
| `tool_executor.py` | 工具执行逻辑 |
| `tool_limiter.py` | 工具调用频率限制 |

### ui/ (显示层)

| 组件 | 职责 |
|------|------|
| `app.py` | Textual 应用主类 |
| `widgets/` | TUI 组件（面板、输入框等） |
| `handlers/` | 事件处理（键盘、焦点） |
| `models/` | 数据模型（消息、配置） |
| `services/` | 配置管理、服务层 |

## 数据流

```
用户输入 → InputBox → on_input_box_send_message
    ↓
BackendClient.process_message(user_input)
    ↓
queue.Queue → BackendServer (独立线程)
    ↓
GraphMemoryClient.send_message_with_history()
    ↓
OpenAI API / DeepSeek API
    ↓
execute_tool() → EmbeddedGraphDB
    ↓
循环调用 API 直到无 tool_calls
    ↓
queue.Queue → 返回结果
    ↓
MessageHistory 显示
```

## 启动流程

```python
# trulymem_entry.py
def main():
    # 配置文件保存在应用根目录
    config_file = application_path / "config.json"
    
    # 加载配置
    config_service = ConfigService(config_file=config_file)
    config = config_service.get_config()
    
    # 创建后端
    backend_server = BackendServer(db_path="graph_memory.db", use_embedded_db=True)
    backend_server.start(api_key=config.api_key, base_url=config.base_url)
    
    # 创建UI
    app = GraphMemoryApp(backend_server=backend_server, config_service=config_service)
    app.run()
    
    backend_server.shutdown()
```

## 布局结构

### 默认视图（右侧展开）

```
┌─────────────────────────────────────┬─────────────────────┐
│                                     │ F2:隐藏侧边栏        │
│  🟠 14:30:25                       │ ────────────────────│
│  用户: 量子力学是什么？              │ API Key: ***       │
│                                     │ 模型: deepseek-chat │
│  🔵 14:30:26                       │ Base URL: ...       │
│  是的！根据记忆...                   │ ────────────────────│
│  [工具:2次] (F3展开)               │ [操作日志]          │
│                                     │ 14:30:26 recall    │
│  ┌─────────────────────────────┐   │ 实体: 量子力学      │
│  │ 🟠 [输入框...]               │   │ ───────────────────│
│  └─────────────────────────────┘   │ >[查询...]         │
└─────────────────────────────────────┴─────────────────────┘
```

### F2后（右侧折叠）

```
┌─────────────────────────────────────┐
│  🟠 14:30:25                       │
│  用户: 量子力学是什么？              │
│                                     │
│  🔵 14:30:26                       │
│  是的！根据记忆...                   │
│  [工具:2次] (F3展开)               │
│                                     │
│  ┌─────────────────────────────┐   │
│  │ 🟠 [输入框...]               │   │
│  └─────────────────────────────┘   │
│  F1:帮助 F2:展开 F5:清屏 F6:退出   │
└─────────────────────────────────────┘
```

## 快捷键

| 按键 | 功能 |
|------|------|
| F1 | 显示帮助 |
| F2 | 切换侧边栏 |
| F3 | 工具详情 |
| F5 | 清屏 |
| F6 | 退出 |

## 技术栈

| 技术 | 用途 |
|------|------|
| Python 3.8+ | 编程语言 |
| Textual 0.47+ | TUI 框架 |
| SQLite | 图数据库（默认内嵌） |
| OpenAI SDK | API 调用（兼容 DeepSeek） |
| threading.Queue | 多线程通信 |
| PyInstaller | 打包 |

## 数据库模式

### SQLite 内嵌（默认）

```python
# core/embedded_db.py
class EmbeddedGraphDB:
    def __init__(self, db_path="graph_memory.db"):
        self.conn = sqlite3.connect(db_path, check_same_thread=False)
```

### 可选：Neo4j

```bash
export USE_EMBEDDED_DB=false
docker run -d --name neo4j -p 7474:7474 -p 7687:7687 neo4j:latest
```

## 工具系统

### 记忆工具 (6个)
- `memory_recall` - 检索记忆
- `memory_commit` - 写入记忆
- `memory_purge` - 删除记忆
- `memory_introspect` - 查看状态
- `memory_archive` - 归档记忆
- `memory_cleanup` - 清理数据

### 人设工具 (2个)
- `persona_update` - 更新人设
- `persona_clear` - 清除人设

### 任务工具 (4个)
- `task_create` - 创建任务
- `task_set_state` - 设置状态
- `task_delete` - 删除任务
- `task_link_info` - 关联信息