TrulyMEM-TrueHumanMEM/docs/zh/quick_start.md

TrulyMEM 启动指南

版本: 多用户版 (v2) — 支持 TUI 登录、多用户隔离、Web 服务内嵌

---

运行方式

快速启动（推荐）

# 从源码
python trulymem_entry.py

# 或打包后
./dist/TrulyMEM

首次使用 —— 登录流程

首次启动会自动检查是否需要迁移旧数据，然后进入登录页面：

1. 新部署 → 直接输入用户名和密码创建账户（首个用户自动成为管理员）
2. 旧版升级 → 自动检测 ~/.trulymem/config.json，引导设置用户名密码，迁移数据
3. 已有账户 → 直接登录进入聊天界面

💡 所有用户数据隔离存储：~/.trulymem/{用户名}/

聊天配置

登录后按 F2 展开右侧配置面板：

1. API Key — 必须（支持 DeepSeek、OpenAI 等）
2. 模型 — 可选，默认已配置
3. Base URL — 可选

配置自动保存，下次启动自动加载。

---

Web 可视化界面

TrulyMEM 的 Web 服务现在内嵌在主进程中（无需独立启动子进程）。

TUI 内启动（管理员专有）

管理员按 F2 打开右侧面板，勾选「启用 Web 服务」即可。

手动启动

python -m core.web_api --port 4096
# 访问 http://localhost:4096

首次访问流程

1. 浏览器打开 http://localhost:4096
2. 无用户 → 自动跳转至设置页，创建管理员账号
3. 有用户 → 跳转至登录页
4. 登录后进入星图可视化页面

Web 功能

页面	访问权限	功能
🌟 星图	所有已登录用户	浏览知识图谱三元组
⚙ 设置	所有已登录用户	修改密码
🧑‍💼 用户管理	仅管理员	添加/删除用户

---

多用户系统

目录结构

~/.trulymem/
├── trulymem.db          # 全局用户数据库（web_users 表）
├── .migrated            # 旧版迁移标记
├── admin/
│   ├── config.json      # 管理员配置
│   └── admin_graph.db   # 管理员知识图谱
└── user2/
    ├── config.json      # user2 配置
    └── user2_graph.db   # user2 知识图谱

角色体系

功能	普通用户	管理员
修改自己密码	✅	✅
配置 API Key / 模型	✅	✅
Web 服务开关（TUI）	❌	✅
Web 登录凭据	❌	✅
查看用户列表	❌	✅
添加/删除用户	❌	✅

⚠️ 首个注册用户自动成为管理员。Web 设置页可添加新用户。

---

快捷键

按键	功能
F1	帮助
F2	切换侧边栏（配置面板）
F3	工具详情
F5	清屏
F6	退出

---

打包构建

# Linux
bash build/build_linux.sh

# macOS
bash build/build_macos.sh

# Windows
build\build_windows.bat

# AppImage
bash build/build_appimage.sh

构建产出：dist/TrulyMEM（单文件，TUI + Web 服务均内嵌于同一二进制）

📦 从 v2 开始，Web 服务作为线程嵌入主程序，不再需要独立打包 trulymem-web。

---

架构说明

通信协议

UI 与后端通过 Packet 协议 通信：

TUI (Textual)  ←→  BackendClient  ←→  queue.Queue  ←→  BackendServer (独立线程)

配置管理

• 用户级存储: ~/.trulymem/{username}/config.json
• Web 配置: ~/.trulymem/trulymem.db（web_users 表）
• 自动加载: 启动时根据登录用户加载对应配置文件
• 动态更新: 运行时修改配置立即生效，自动持久化

Web 服务架构

┌──────────────────────┐
│    TrulyMEM 主进程    │
│  ┌──────┐ ┌────────┐ │
│  │ TUI  │ │ Flask  │ │  ← 同一进程，不同线程
│  │      │ │ Thread │ │
│  └──────┘ └────────┘ │
└──────────────────────┘

---

常见问题

Python 未找到

安装 Python 3.8+：https://www.python.org/downloads/

依赖安装失败

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -r requirements.txt

API Key 无效

检查 API Key 格式，确保无多余空格。可在 TUI 右侧面板重新配置。

管理员账号丢失

数据库中第一个注册账号总是 admin。如果所有用户都丢失了 admin 权限，删除用户目录下的 trulymem.db 后重新注册即可。

旧版数据迁移

检测到旧版 ~/.trulymem/config.json 和 graph_memory.db 时，TUI 启动时自动进入迁移引导。迁移后旧文件保留，不会删除。

---

开发命令

pip install -r requirements.txt
pytest tests/
bash build/build_linux.sh