jianf/TrulyMEM-TrueHumanMEM-local
1
0
Fork 0
Code Issues Pull Requests Actions 10 Packages Projects Releases Wiki Activity

Docs: sync all docs with actual code implementation

Browse Source 
Changes:
- README.md: Fix executable download wording (not pre-built)
- 架构.md: Remove Cypher references (no Cypher in SQLite mode), note cypher_query_box is display-only
- 一键启动指南.md: Remove deleted scripts (start.bat, install.bat), remove made-up startup timings
This commit is contained in:
root
2026-04-12 16:42:44 +08:00
parent 1d11ad6c9a
commit 0d8a7592ad
3 changed files with 129 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
docs/一键启动指南.md
View File

@ -1,127 +1,50 @@
# TrulyMEM 一键启动指南
# TrulyMEM 启动指南
## 快速开始
## 运行方式
### Windows
### 从源码运行
```bash
# 方法1: 双击运行
双击 start.bat
# 克隆仓库
git clone <repo-url>
cd TrulyMEM-TrueHumanMEM
# 方法2: 命令行
start.bat
# 安装依赖
pip install -r requirements.txt
# 方法3: Python
# 运行
python trulymem_entry.py
```
### Linux / macOS
### 打包后运行
打包后会生成可执行文件（Windows: TrulyMEM.exe, Linux/macOS: TrulyMEM）：
```bash
# 方法1: Python直接运行
python3 trulymem_entry.py
# 方法2: 打包后的可执行文件
# Linux/macOS
chmod +x TrulyMEM
./TrulyMEM
# Windows
TrulyMEM.exe
```
## 启动流程
```
[Step 1/3] 检查 Python
↓
[Step 2/3] 安装依赖
- 安装 requirements.txt 中的依赖
↓
[Step 3/3] 启动应用
↓
✅ 系统初始化成功！
```
## 启动时间
- **首次启动**: 约1-2分钟（安装依赖）
- **后续启动**: 约30秒
## 系统要求
### 必需
- **Python 3.8+**
- **DeepSeek API Key** (或 OpenAI 兼容 API Key)
- **API Key**（DeepSeek、OpenAI 或其他兼容 API）
### 可选
## 首次配置
- **Git** - 用于克隆仓库
## 首次使用
### 1. 启动应用
```bash
python trulymem_entry.py
```
### 2. 配置 API Key
1. 按 **F2** 展开侧边栏
2. 在 API Key 输入框输入密钥
3. 按 **Enter** 保存
### 3. 开始对话
- 在底部输入框输入消息
- 按 **Enter** 发送
## 获取 API Key
### DeepSeek
1. 访问：https://platform.deepseek.com/
2. 注册账号
3. 创建 API Key
4. 复制密钥
### 其他兼容API
- OpenAI
- 其他兼容OpenAI格式的API（如 Azure OpenAI）
## 常见问题
### Q: Python 未找到
**A:** 安装 Python 3.8+
- Windows: https://www.python.org/downloads/
- Linux: `sudo apt install python3`
- macOS: `brew install python3`
### Q: 依赖安装失败
**A:** 手动安装
```bash
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pip install -r requirements.txt
```
### Q: API Key 无效
**A:** 检查API Key格式
- 应以 `sk-` 开头（DeepSeek/OpenAI）
- 无多余空格
- 正确复制
### Q: 提示"请先配置API Key"
**A:** 按 F2 展开侧边栏，在 API Key 输入框中输入密钥后按 Enter
1. 运行应用
2. 按 **F2** 展开侧边栏
3. 输入 **API Key**
4. 按 **Enter** 保存
## 快捷键
| 快捷键 | 功能 |
|--------|------|
| 按键 | 功能 |
|------|------|
| F1 | 帮助 |
| F2 | 切换侧边栏 |
| F3 | 工具详情 |
@ -131,69 +54,39 @@ pip install -r requirements.txt
## 数据存储
- **数据库**: `graph_memory.db`
- **位置**: 应用目录
- **格式**: SQLite（内嵌，无需外部数据库）
- **可备份**: 是，直接复制文件即可
- **数据库**: `graph_memory.db`（应用目录）
- **配置**: `config.json`（应用目录）
- **格式**: SQLite
## 更新应用
## 常见问题
### Python 未找到
安装 Python 3.8+：https://www.python.org/downloads/
### 依赖安装失败
```bash
# 拉取最新代码
git pull
# 重新安装依赖（如有更新）
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pip install -r requirements.txt
# 重新启动
python trulymem_entry.py
```
## 清理数据
### API Key 无效
检查 API Key 格式，确保无多余空格。
## 开发命令
```bash
# 删除数据库
rm graph_memory.db
# 重新启动会创建新数据库
python trulymem_entry.py
```
## 提示
- 首次启动需要安装依赖，请耐心等待
- API Key 只需配置一次（自动保存）
- 数据自动保存，无需手动操作
- 可以随时按 F6 退出
## 从源码运行
```bash
# 克隆仓库
git clone https://github.com/yourusername/trulymem.git
cd trulymem
# 安装依赖
pip install -r requirements.txt
# 运行
python -m graph_memory_tui.main
# 或
python trulymem_entry.py
# 运行测试
pytest tests/
# 打包（需 PyInstaller）
python build_windows.bat # Windows
bash build_linux.sh # Linux
```
## 打包应用
### Windows
```bash
python build_windows.bat
```
### Linux
```bash
bash build_linux.sh
```
开始使用吧！

176
docs/架构.md
View File

@ -10,8 +10,8 @@
```
TrulyMEM-TrueHumanMEM/
├── trulymem_entry.py # 打包入口（独立可执行文件）
├── graph_memory_tui/ # 核心应用包
├── trulymem_entry.py # 打包入口
├── graph_memory_tui/ # 核心应用包 (38 个 Python 文件)
│ ├── app.py # TUI 主应用 (GraphMemoryApp)
│ ├── main.py # 模块入口
│ ├── __init__.py
@ -19,54 +19,54 @@ TrulyMEM-TrueHumanMEM/
│ │ ├── __init__.py
│ │ ├── imports.py # 动态导入（内嵌DB vs Neo4j）
│ │ ├── embedded_db.py # SQLite 图数据库实现
│ │ ├── graph_client.py # Neo4j 客户端（可选）
│ │ ├── graph_client.py # Neo4j 客户端（可选，未使用）
│ │ ├── optimized_operations.py
│ │ ├── prompts/ # 提示词管理
│ │ ├── prompts/ # 提示词管理
│ │ │ ├── __init__.py
│ │ │ ├── prompt_manager.py
│ │ │ └── templates/
│ │ │ └── system_prompt.md
│ │ └── tools/ # 工具定义与执行
│ │ └── tools/ # 工具定义与执行
│ │ ├── __init__.py
│ │ ├── memory_tools.py # 6个记忆工具 + 人设/任务工具
│ │ ├── memory_tools.py # 工具定义
│ │ ├── tool_executor.py # 工具执行器
│ │ └── tool_limiter.py # 调用限制器
│ ├── models/ # 数据模型
│ ├── models/ # 数据模型
│ │ ├── __init__.py
│ │ ├── message.py # Message, ToolCall, ToolResult
│ │ ├── config.py # AppConfig
│ │ └── log_entry.py # LogEntry
│ ├── services/ # 服务层
│ │ ├── message.py # Message, ToolCall, ToolResult
│ │ ├── config.py # AppConfig
│ │ └── log_entry.py # LogEntry
│ ├── services/ # 服务层
│ │ ├── __init__.py
│ │ ├── config_manager.py # 配置持久化
│ │ ├── config_manager.py # 配置持久化
│ │ ├── config_service.py
│ │ ├── chat_service.py
│ │ └── tool_service.py
│ ├── handlers/ # 事件处理
│ ├── handlers/ # 事件处理
│ │ ├── __init__.py
│ │ ├── focus_handler.py
│ │ ├── key_handler.py
│ │ └── message_handler.py
│ ├── widgets/ # TUI 组件
│ ├── widgets/ # TUI 组件
│ │ ├── __init__.py
│ │ ├── left_panel.py # 左侧主对话区
│ │ ├── right_panel.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 查询
│ │ ├── 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} # 打包脚本
├── tests/ # 测试（pytest）
├── docs/ # 文档
├── requirements.txt # 依赖
└── build_*.{bat,sh} # 打包脚本
```
## 布局结构
@ -76,22 +76,16 @@ TrulyMEM-TrueHumanMEM/
```
┌─────────────────────────────────────┬─────────────────────┐
│ │ F2:隐藏侧边栏 │
│ ┌─────────────────────────────┐ │ ────────────────────│
│ │ 🟠 用户: 量子力学是什么？ │ │ API Key: *** │
│ └─────────────────────────────┘ │ 模型: deepseek-chat ▼│
│ │ Base URL: ... │
│ ┌─────────────────────────────┐ │ ────────────────────│
│ │ 🔵 模型: 根据记忆... │ │ [图操作日志] │
│ │ │ │ ▼ 14:32:15 recall │
│ │ 是的！根据记忆... │ │ 实体: 量子力学... │
│ │ │ │ 关系: 3条 │
│ │ [工具:2次] (F3展开) │ │ ───────────────────│
│ └─────────────────────────────┘ │ >[查询图...] │
│ │ F4:执行 │
│ ┌─────────────────────────────┐ └─────────────────────┘
│ │ 🟠 [输入框...] │
│ └─────────────────────────────┘
│ F1:帮助 F2:隐藏侧边栏 F5:清屏 F6:退出│
│ 🟠 14:30:25 │ ────────────────────│
│ 用户: 量子力学是什么？ │ API Key: *** │
│ │ 模型: deepseek-chat │
│ 🔵 14:30:26 │ Base URL: ... │
│ 是的！根据记忆... │ ────────────────────│
│ [工具:2次] (F3展开) │ [操作日志] │
│ │ 14:30:26 recall │
│ ┌─────────────────────────────┐ │ 实体: 量子力学 │
│ │ 🟠 [输入框...] │ │ ───────────────────│
│ └─────────────────────────────┘ │ >[查询...] │
└─────────────────────────────────────┴─────────────────────┘
```
@ -99,101 +93,85 @@ TrulyMEM-TrueHumanMEM/
```
┌─────────────────────────────────────┐
│ 🟠 14:30:25 │
│ 用户: 量子力学是什么？ │
│ │
│ ┌─────────────────────────────┐ │
│ │ 🟠 用户: 量子力学是什么？ │ │
│ └─────────────────────────────┘ │
│ │
│ ┌─────────────────────────────┐ │
│ │ 🔵 模型: 根据记忆... │ │
│ │ │ │
│ │ 是的！根据记忆... │ │
│ │ │ │
│ │ [工具:2次] (F3展开) │ │
│ └─────────────────────────────┘ │
│ 🔵 14:30:26 │
│ 是的！根据记忆... │
│ [工具:2次] (F3展开) │
│ │
│ ┌─────────────────────────────┐ │
│ │ 🟠 [输入框...] │ │
│ └─────────────────────────────┘ │
│ F1:帮助 F2:展开侧边栏 F5:清屏 F6:退出│
│ │
│ F1:帮助 F2:展开 F5:清屏 F6:退出 │
└─────────────────────────────────────┘
```
## 快捷键映射
## 快捷键
| 按键 | 功能 |
|------|------|
| `F1` | 显示帮助面板（快捷键列表） |
| `F2` | 切换右侧边栏 展开/折叠 |
| `F3` | 展开/折叠当前模型回复的工具调用详情 |
| `F4` | 右侧 Cypher 查询框获得焦点（若侧边栏折叠则自动展开） |
| `F5` | 清屏（保留记忆，清空显示） |
| `F6` / `Ctrl+C` | 退出程序 |
## 焦点管理
- **默认焦点**: 启动后焦点自动位于底部输入框
- **F4 特殊行为**: 按下 F4 时，若侧边栏处于折叠状态，先自动展开侧边栏，再将焦点移至 Cypher 查询框
## 视觉样式
| 元素 | 样式 |
|------|------|
| 用户消息 | 🟠 橙色头部标识 |
| 模型消息 | 🔵 蓝色头部标识 |
| 底部输入框 | 橙色边框，聚焦时高亮 |
| 工具调用摘要 | 灰色括号 `[工具:N次]` |
| 右侧边栏 | 深色背景，宽度 70 字符 |
| 右侧日志区 | 格式化文本，最新在上 |
| F1 | 显示帮助 |
| F2 | 切换侧边栏 |
| F3 | 工具详情 |
| F4 | 聚焦查询框 |
| F5 | 清屏 |
| F6 | 退出 |
## 组件职责
### 左侧区域（主对话区）
- **MessageHistory**: 滚动容器，显示消息历史
- **InputBox**: 固定底部，消息输入
- **LeftPanel**: 左上面板容器
### 左侧区域
- **MessageHistory**: 消息历史容器
- **InputBox**: 底部输入框
### 右侧区域（侧边栏）
- **RightPanel**: 侧边栏容器，可折叠（宽度 70）
### 右侧区域
- **RightPanel**: 侧边栏容器（宽度 70）
- **ConfigSection**: 配置区（API Key、模型选择、Base URL）
- **OperationLog**: 图操作日志，只读
- **CypherQueryBox**: 直接执行 Cypher 查询
- **OperationLog**: 操作日志
- **CypherQueryBox**: 查询框（注：目前仅作展示，无 Cypher 查询功能）
## 数据流
```
用户输入 → InputBox.on_input_box_send_message
用户输入 → InputBox → app.on_input_box_send_message
↓
GraphMemoryClient.send_message_with_history()
↓
OpenAI API / DeepSeek API
↓
检查 tool_calls → execute_tool() → EmbeddedGraphDB / Neo4jGraph
检查 tool_calls → execute_tool() → EmbeddedGraphDB
↓
循环调用 API 直到无 tool_calls
↓
最终回复 → MessageHistory (左侧)
↓
工具记录 → OperationLog (右侧)
最终回复 → MessageHistory + OperationLog
```
## 技术实现
## 技术栈
- **框架**: textual（Python TUI 框架）
- **布局**: CSS-like 样式，右侧固定宽度 70 字符
- **状态管理**: App 实例持有配置、数据库连接、API 客户端
- **数据库**: SQLite（默认内嵌）或 Neo4j（可选）
- **LLM 接口**: OpenAI SDK，兼容 DeepSeek 等
| 技术 | 用途 |
|------|------|
| 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 # SQLite
else:
from .graph_client import Neo4jGraph # Neo4j
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
```
## 工具系统