# TrulyMEM 架构设计

## 核心原则

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

## 项目结构

```
TrulyMEM-TrueHumanMEM/
├── trulymem_entry.py          # 打包入口
├── graph_memory_tui/          # 核心应用包 (38 个 Python 文件)
│   ├── 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    # 工具定义
│   │       ├── 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/                    # 测试（pytest）
├── docs/                     # 文档
├── requirements.txt          # 依赖
└── build_*.{bat,sh}        # 打包脚本
```

## 布局结构

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

```
┌─────────────────────────────────────┬─────────────────────┐
│                                     │ 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 | 工具详情 |
| F4 | 聚焦查询框 |
| F5 | 清屏 |
| F6 | 退出 |

## 组件职责

### 左侧区域
- **MessageHistory**: 消息历史容器
- **InputBox**: 底部输入框

### 右侧区域
- **RightPanel**: 侧边栏容器（宽度 70）
- **ConfigSection**: 配置区（API Key、模型选择、Base URL）
- **OperationLog**: 操作日志
- **CypherQueryBox**: 查询框（注：目前仅作展示，无 Cypher 查询功能）

## 数据流

```
用户输入 → InputBox → app.on_input_box_send_message
    ↓
GraphMemoryClient.send_message_with_history()
    ↓
OpenAI API / DeepSeek API
    ↓
检查 tool_calls → execute_tool() → EmbeddedGraphDB
    ↓
循环调用 API 直到无 tool_calls
    ↓
最终回复 → MessageHistory + OperationLog
```

## 技术栈

| 技术 | 用途 |
|------|------|
| Python 3.8+ | 编程语言 |
| Textual 0.47+ | TUI 框架 |
| SQLite | 图数据库（默认内嵌） |
| OpenAI SDK | API 调用（兼容 DeepSeek） |
| Neo4j | 可选数据库（需 Docker） |
| PyInstaller | 打包 |

## 数据库模式

### 默认：SQLite 内嵌

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

### 可选：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` - 关联信息