# TrueHumanMEM - Graph Memory TUI
> The More Human Choice.
一个让 AI 拥有自知、可塑、有分寸感长期记忆的图记忆系统，配备现代化终端用户界面。
## 📖 目录
- [背景与理念](#背景与理念)
- [核心特性](#核心特性)
- [架构设计](#架构设计)
- [快速开始](#快速开始)
- [工具说明](#工具说明)
- [图数据库模式](#图数据库模式)
- [与传统方案的对比](#与传统方案的对比)
- [路线图](#路线图)
- [限制与注意事项](#限制与注意事项)
---
## 背景与理念
### 传统 AI 记忆的三大困境
| 困境 | 表现 | 根源 |
|------|------|------|
| 上下文窗口天花板 | 对话越长，记忆越模糊，成本越高 | 依赖原始对话历史传递信息 |
| "录音机式"记忆 | 仅能复述原文，无法理解关系与联想 | 向量检索只做语义匹配，缺乏结构 |
| "不懂认错"的固执 | 错误信息无法修正，矛盾记录并存 | 记忆只有"写入"和"读取"，没有"更新"和"删除" |
### 我们的答案：像人一样记忆
TrueHumanMEM 的设计哲学不是做一个更"精准"的记忆数据库，而是让 AI 具备以下四种人类记忆的本质特征：
1. **选择性** —— 只记录有价值的关系，不记流水账。
2. **模糊性** —— 能推断，也能坦诚地表达不确定性。
3. **可塑性** —— 允许修正、覆盖旧记忆，认知随对话演化。
4. **自明性** —— 能区分"用户陈述"与"模型推断"，记忆自知来源。
TrueHumanMEM 不是更强大的搜索引擎，而是更像人的记忆伙伴。
---
## 核心特性
### 🧠 最小化上下文窗口依赖
上下文仅用于协议适配，不承载对话记忆。
表面上，系统仍通过 messages 列表与 LLM API 交互——这是当前 Function Calling 接口的标准要求。但实际上：
- **不传递历史对话**：每轮请求的 messages 仅包含系统提示、当前用户输入、上一轮的工具调用结果。
- **不累积轮次**：过去的用户消息和助手回复不会被追加到后续请求中。模型无法通过翻看聊天记录来回忆信息。
- **记忆外置**：所有需要跨轮次保留的事实、关系、偏好，全部写入 Neo4j 图数据库。当需要时，模型必须显式调用 memory_recall 工具，主动从图库中检索。
这种设计确保了：上下文长度不随对话轮次线性增长，记忆能力不囿于窗口上限。
### 🔗 结构化关系推理
- 以三元组 (主体, 关系, 客体) 存储事实，天然支持多跳路径查询。
- 即使信息未被用户直接陈述，系统也可通过路径组合进行推断。
### ✍️ 自主记忆决策
- 模型通过函数调用机制自主触发检索、写入或修正操作，避免硬编码管道。
- 基于对话语境判断"什么值得记"、"何时该查"。
### 🔄 完整的记忆生命周期管理
| 状态 | 含义 | 操作 |
|------|------|------|
| active | 当前有效记忆 | 写入时创建 |
| deleted | 软删除，逻辑失效 | 软删除操作 |
| superseded | 已被新关系替代 | 替代模式操作 |
| archived | 归档，低频访问 | 归档操作 |
| 物理删除 | 彻底清理 | 清理操作 |
### 🎯 置信度与来源标记
- 每条关系携带数值置信度，存储层区分"确凿"与"推测"。
- 表达层将不确定性转化为自然语言语气，实现从存储到表达的完整自知闭环。
### 🔒 隐私友好，数据可本地化
- 图库可部署于本地或私有环境，记忆数据由用户掌控。
### 🖥️ 现代化终端界面
- 基于 Textual 框架的 TUI 界面
- 实时消息显示与工具调用可视化
- 侧边栏配置与操作日志
- 跨平台支持（Windows/Linux/macOS）
---
## 架构设计
```
┌─────────────────────────────────────────────────────────────┐
│ 用户输入 │
└─────────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ LLM API (with Function Calling) │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ System Prompt: 记忆助手角色 │ │
│ │ + 当前用户输入 + 上一轮工具调用结果（极简上下文） │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────┘
│ 模型自主决策调用工具
┌───────────────┼───────────────┬───────────────┐
▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ recall │ │ commit │ │ purge │ │ introspect │
└─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ │ │ │
└───────────────┴───────┬───────┴───────────────┘
▼
┌─────────────────────────┐
│ Neo4j 图数据库 │
│ (实体节点 + 关系边) │
└─────────────────────────┘
```
- **轻量级上下文**：每轮仅包含系统提示、上一轮工具调用结果、当前用户输入。过往对话历史不累积。
- **持续工具调用循环**：模型可在一次回复中调用多个工具，直至给出最终文本回复。
- **可观测性支持**：所有工具调用记录于会话日志，支持审计追踪与调试回溯。
---
## 快速开始
### 前置要求
- **Python 3.8+**
- **Docker** (用于 Neo4j 数据库)
- **DeepSeek API Key**（或兼容 OpenAI 格式的任意 LLM API）
### 一键启动（推荐）
#### Windows
```bash
# 双击运行
start.bat
# 或命令行
python start.py
```
#### Linux / macOS
```bash
# Shell脚本
chmod +x start.sh
./start.sh
# 或Python
python3 start.py
```
启动脚本会自动：
1. ✅ 启动 Docker (优先WSL，回退到Docker Desktop)
2. ✅ 启动 Neo4j 数据库
3. ✅ 创建虚拟环境
4. ✅ 安装依赖
5. ✅ 启动 TUI 应用
### 手动启动
#### 1. 克隆仓库
```bash
git clone https://github.com/your-org/TrueHumanMEM.git
cd TrueHumanMEM
```
#### 2. 安装依赖
```bash
pip install -r requirements.txt
```
#### 3. 启动 Neo4j
```bash
# 使用Docker
docker run -d --name neo4j \
-p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=neo4j/graphmemory123 \
neo4j:latest
```
#### 4. 配置环境变量
```bash
export DEEPSEEK_API_KEY="your-api-key"
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="graphmemory123"
```
#### 5. 运行应用
**TUI 界面（推荐）**
```bash
python -m graph_memory_tui.main
```
**命令行 Demo**
```bash
python graph_memory_demo.py
```
### 使用 TUI 界面
1. **配置 API Key**
- 按 F2 展开侧边栏
- 点击"配置"
- 输入你的 DeepSeek API Key
- 按 Enter 保存
2. **开始对话**
- 输入消息
- 按 Enter 发送
- 查看工具调用和AI响应
3. **快捷键**
- F1: 帮助
- F2: 切换侧边栏
- F3: 工具详情
- F5: 清屏
- F6: 退出
---
## 工具说明
系统向模型暴露 6 个记忆管理工具，由模型根据对话需求自主调用。
| 工具名 | 描述 | 关键参数 |
|--------|------|----------|
| memory_recall | 检索相关子图 | query_intent (str): 关键词意图
seed_entities (List[str]): 起始实体
depth (int): 遍历深度
time_range (str, 可选): 时间范围 |
| memory_commit | 写入三元组 | triplets (List[Dict]): 每项含 subject, relation, object, confidence (float, 0.0-1.0) |
| memory_purge | 删除或替代记忆 | criteria (Dict): 匹配条件
mode (str): soft / supersede
new_relation (Dict, 可选): 替代关系 |
| memory_introspect | 查看当前会话元数据 | session_id (str, 可选) |
| memory_archive | 归档旧关系 | days (int): 归档天数阈值 |
| memory_cleanup | 物理清理已删除数据 | dry_run (bool): 预览模式 |
---
## 图数据库模式
### 节点（Entity）
| 属性 | 类型 | 描述 |
|------|------|------|
| name | String | 实体唯一标识 |
| type | String | 实体类型（模型动态提议） |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 最后更新时间 |
| mention_count | Integer | 被提及次数 |
### 关系（RELATES）
| 属性 | 类型 | 描述 |
|------|------|------|
| type | String | 关系类型 |
| created_at | DateTime | 关系创建时间 |
| session_id | String | 所属会话 ID |
| turn_id | Integer | 会话内轮次编号 |
| status | String | active / deleted / superseded / archived |
| confidence | Float | 置信度 0.0 ~ 1.0 |
| date_bucket | String | 日期分桶 (YYYY-MM-DD) |
| supersedes | Integer | （可选）指向替代关系 ID |
**索引与约束**：实体名与会话 ID 唯一约束；关系属性建立索引以确保查询性能。
---
## 与传统方案的对比
| 维度 | 传统上下文窗口 | 向量 RAG | TrueHumanMEM |
|------|----------------|----------|--------------|
| 记忆跨度 | 受窗口长度限制 | 检索精度随数据量下降 | 跨会话持久化，图结构保证精度 |
| 关系推理 | 依赖模型上下文推理 | 仅语义相似匹配 | 原生多跳路径查询 |
| 记忆修正 | 只能追加新消息 | 旧向量无法更新 | 完整状态机（软删除、替代） |
| 不确定性表达 | 无 | 无 | 置信度 + 语气标记 |
| 数据主权 | 全部上传 API | 向量库常为云端 | 图库可本地化部署 |
| 可解释性 | 黑盒 | 难以解释召回原因 | 显式关系路径，可审计 |
---
## 路线图
### Phase 1: 核心稳定（当前）
- [X] 核心六工具 + Neo4j 集成
- [X] 函数调用驱动自主决策
- [X] 软删除与替代模式
- [X] TUI 界面
- [X] 一键启动脚本
- [X] 多语言支持
### Phase 2: 体验优化
- [ ] 来源标记增强：存储层显式区分"用户陈述"与"模型推断"
- [ ] 端侧轻量化：适配轻量级图存储，支持资源受限环境
- [ ] 全文索引优化：提升大规模数据检索性能
- [ ] 人工干预接口：支持显式记忆编辑与强制检索指令
### Phase 3: 能力扩展
- [ ] 多模态记忆：支持非文本记忆关联
- [ ] 可视化界面：图形化展示个人知识图谱
- [ ] 流式输出：实时显示AI响应
---
## 限制与注意事项
- **事实准确性依赖底层模型能力**：系统通过 LLM 进行关系抽取与推断，可能产生错误事实，建议关键信息人工复核。
- **函数调用能力依赖**：模型需支持稳定的 function calling 接口，不同 LLM 表现可能存在差异。
- **性能基准待补充**：当前版本未针对超大规模图谱（千万级节点）进行优化，极端场景下查询延迟可能上升。
- **隐私边界**：本地部署仅保证数据存储位置可控，LLM API 调用仍受服务商条款约束。
---
## 文档
详细文档请查看 `docs/` 目录：
- [架构设计](docs/架构.md)
- [一键启动指南](docs/一键启动指南.md)
- [API配置指南](docs/API配置指南.md)
---
## 贡献
欢迎任何形式的贡献！请先阅读贡献指南。
---
## 许可证
本项目采用 MIT License。
---
**TrueHumanMEM —— 让 AI 的记忆方式，更像人。**