# TrulyMEM 架构设计

## 核心原则

- 键盘驱动，零鼠标依赖
- 极简视觉，信息密度优先
- 工具痕迹默认隐藏，需要时可展开

## 项目结构

```
TrulyMEM-TrueHumanMEM/
├── trulymem_entry.py          # 打包入口（独立可执行文件）
├── graph_memory_tui/          # 核心应用包
│   ├── app.py                 # TUI 主应用 (GraphMemoryApp)
│   ├── main.py                # 模块入口
│   ├── __init__.py
│   ├── core/                  # 核心逻辑
│   │   ├── __init__.py
│   │   ├── imports.py         # 动态导入（内嵌DB vs Neo4j）
│   │   ├── embedded_db.py     # SQLite 图数据库实现
│   │   ├── graph_client.py    # Neo4j 客户端（可选）
│   │   ├── optimized_operations.py
│   │   ├── prompts/          # 提示词管理
│   │   │   ├── __init__.py
│   │   │   ├── prompt_manager.py
│   │   │   └── templates/
│   │   │       └── system_prompt.md
│   │   └── tools/             # 工具定义与执行
│   │       ├── __init__.py
│   │       ├── memory_tools.py    # 6个记忆工具 + 人设/任务工具
│   │       ├── tool_executor.py   # 工具执行器
│   │       └── tool_limiter.py    # 调用限制器
│   ├── models/                # 数据模型
│   │   ├── __init__.py
│   │   ├── message.py         # Message, ToolCall, ToolResult
│   │   ├── config.py          # AppConfig
│   │   └── log_entry.py       # LogEntry
│   ├── services/              # 服务层
│   │   ├── __init__.py
│   │   ├── config_manager.py  # 配置持久化
│   │   ├── config_service.py
│   │   ├── chat_service.py
│   │   └── tool_service.py
│   ├── handlers/              # 事件处理
│   │   ├── __init__.py
│   │   ├── focus_handler.py
│   │   ├── key_handler.py
│   │   └── message_handler.py
│   ├── widgets/               # TUI 组件
│   │   ├── __init__.py
│   │   ├── 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 # Cypher 查询
│   │   └── status_bar.py     # 状态栏
│   └── styles/               # 样式文件
│       ├── __init__.py
│       ├── app.css
│       ├── components.css
│       └── messages.css
├── tests/                     # 测试
├── docs/                      # 文档
├── requirements.txt           # 依赖
└── build_*.{bat,sh}          # 打包脚本
```

## 布局结构

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

```
┌─────────────────────────────────────┬─────────────────────┐
│                                     │ F2:隐藏侧边栏        │
│  ┌─────────────────────────────┐   │ ────────────────────│
│  │ 🟠 用户: 量子力学是什么？      │   │ API Key: ***       │
│  └─────────────────────────────┘   │ 模型: deepseek-chat ▼│
│                                     │ Base URL: ...       │
│  ┌─────────────────────────────┐   │ ────────────────────│
│  │ 🔵 模型: 根据记忆...          │   │ [图操作日志]         │
│  │                             │   │ ▼ 14:32:15 recall  │
│  │ 是的！根据记忆...              │   │   实体: 量子力学... │
│  │                             │   │   关系: 3条         │
│  │ [工具:2次] (F3展开)          │   │ ───────────────────│
│  └─────────────────────────────┘   │ >[查询图...]       │
│                                     │ F4:执行            │
│  ┌─────────────────────────────┐   └─────────────────────┘
│  │ 🟠 [输入框...]               │
│  └─────────────────────────────┘
│  F1:帮助 F2:隐藏侧边栏 F5:清屏 F6:退出│
└─────────────────────────────────────┴─────────────────────┘
```

### F2后（右侧折叠）

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

## 快捷键映射

| 按键 | 功能 |
|------|------|
| `F1` | 显示帮助面板（快捷键列表） |
| `F2` | 切换右侧边栏 展开/折叠 |
| `F3` | 展开/折叠当前模型回复的工具调用详情 |
| `F4` | 右侧 Cypher 查询框获得焦点（若侧边栏折叠则自动展开） |
| `F5` | 清屏（保留记忆，清空显示） |
| `F6` / `Ctrl+C` | 退出程序 |

## 焦点管理

- **默认焦点**: 启动后焦点自动位于底部输入框
- **F4 特殊行为**: 按下 F4 时，若侧边栏处于折叠状态，先自动展开侧边栏，再将焦点移至 Cypher 查询框

## 视觉样式

| 元素 | 样式 |
|------|------|
| 用户消息 | 🟠 橙色头部标识 |
| 模型消息 | 🔵 蓝色头部标识 |
| 底部输入框 | 橙色边框，聚焦时高亮 |
| 工具调用摘要 | 灰色括号 `[工具:N次]` |
| 右侧边栏 | 深色背景，宽度 70 字符 |
| 右侧日志区 | 格式化文本，最新在上 |

## 组件职责

### 左侧区域（主对话区）
- **MessageHistory**: 滚动容器，显示消息历史
- **InputBox**: 固定底部，消息输入
- **LeftPanel**: 左上面板容器

### 右侧区域（侧边栏）
- **RightPanel**: 侧边栏容器，可折叠（宽度 70）
- **ConfigSection**: 配置区（API Key、模型选择、Base URL）
- **OperationLog**: 图操作日志，只读
- **CypherQueryBox**: 直接执行 Cypher 查询

## 数据流

```
用户输入 → InputBox.on_input_box_send_message
    ↓
GraphMemoryClient.send_message_with_history()
    ↓
OpenAI API / DeepSeek API
    ↓
检查 tool_calls → execute_tool() → EmbeddedGraphDB / Neo4jGraph
    ↓
循环调用 API 直到无 tool_calls
    ↓
最终回复 → MessageHistory (左侧)
    ↓
工具记录 → OperationLog (右侧)
```

## 技术实现

- **框架**: textual（Python TUI 框架）
- **布局**: CSS-like 样式，右侧固定宽度 70 字符
- **状态管理**: App 实例持有配置、数据库连接、API 客户端
- **数据库**: SQLite（默认内嵌）或 Neo4j（可选）
- **LLM 接口**: OpenAI SDK，兼容 DeepSeek 等

## 数据库双模式

```python
# core/imports.py
if USE_EMBEDDED_DB:
    from .embedded_db import EmbeddedGraphDB as Neo4jGraph  # SQLite
else:
    from .graph_client import Neo4jGraph  # Neo4j
```

## 工具系统

### 记忆工具 (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` - 关联信息