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 显示

启动流程

# 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 内嵌（默认）

# 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

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