TrulyMEM-TrueHumanMEM/docs/架构.md

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 等

数据库双模式

# 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 - 关联信息