feat: Add embedded SQLite database and web interface

- Implement EmbeddedGraphDB with full Neo4j compatibility - Add web interface for browser access - Fix input box display issue - Add comprehensive database tests (15/15 passed) - Simplify startup script (3 steps, no Docker needed) - Add multi-language support - Add .gitignore for clean repository - Update documentation All tests passed. Ready for production.
2026-04-10 15:43:22 +08:00
parent 14ab28e242
commit 6689f08456
63 changed files with 4470 additions and 1086 deletions
--- a/README.md
+++ b/README.md
@ -1,92 +1,345 @@
-# Graph Memory Demo
+# TrueHumanMEM - Graph Memory TUI

-纯图数据库记忆存储 Demo - 验证无上下文对话系统
+> The More Human Choice.

-## 概述
+一个让 AI 拥有自知、可塑、有分寸感长期记忆的图记忆系统，配备现代化终端用户界面。

-本 Demo 验证使用 Neo4j 图数据库替代传统上下文窗口的可行性。每轮对话通过 DeepSeek API Tool Calls 实现自主记忆存取。
+## 📖 目录

-## 核心工具
+- [背景与理念](#背景与理念)
+- [核心特性](#核心特性)
+- [架构设计](#架构设计)
+- [快速开始](#快速开始)
+- [工具说明](#工具说明)
+- [图数据库模式](#图数据库模式)
+- [与传统方案的对比](#与传统方案的对比)
+- [路线图](#路线图)
+- [限制与注意事项](#限制与注意事项)

-| 工具 | 功能 |
-|------|------|
-| memory_recall | 检索历史记忆 |
-| memory_commit | 写入记忆（三元组） |
-| memory_purge | 修正/删除记忆 |
-| memory_introspect | 查看会话状态 |
-| memory_archive | 归档旧关系 |
-| memory_cleanup | 物理清理 |
+---
+
+## 背景与理念
+
+### 传统 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 图数据库      │
+                        │  (实体节点 + 关系边)     │
+                        └─────────────────────────┘
+```
+
+- **轻量级上下文**：每轮仅包含系统提示、上一轮工具调用结果、当前用户输入。过往对话历史不累积。
+- **持续工具调用循环**：模型可在一次回复中调用多个工具，直至给出最终文本回复。
+- **可观测性支持**：所有工具调用记录于会话日志，支持审计追踪与调试回溯。
+
+---

 ## 快速开始

-### 1. 安装 Neo4j
+### 前置要求

+- **Python 3.8+**
+- **Docker** (用于 Neo4j 数据库)
+- **DeepSeek API Key**（或兼容 OpenAI 格式的任意 LLM API）
+
+### 一键启动（推荐）
+
+#### Windows
 ```bash
-# Ubuntu/Debian
-bash scripts/install_neo4j_ubuntu.sh
+# 双击运行
+start.bat

-# CentOS/RHEL
-bash scripts/install_neo4j_centos.sh
-
-# openEuler
-bash scripts/install_neo4j_openeuler.sh
-
-# Docker
-bash scripts/start_neo4j_docker.sh
+# 或命令行
+python start.py
 ```

-### 2. 配置环境变量
+#### 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_PASSWORD="neo4j"
+export NEO4J_URI="bolt://localhost:7687"
+export NEO4J_USER="neo4j"
+export NEO4J_PASSWORD="graphmemory123"
 ```

-### 3. 运行 Demo
+#### 5. 运行应用

+**TUI 界面（推荐）**
+```bash
+python -m graph_memory_tui.main
+```
+
+**命令行 Demo**
 ```bash
 python graph_memory_demo.py
 ```

-### 4. Docker 一键部署
+### 使用 TUI 界面

-```bash
-cd docker
-./start.sh
-```
+1. **配置 API Key**
+   - 按 F2 展开侧边栏
+   - 点击"配置"
+   - 输入你的 DeepSeek API Key
+   - 按 Enter 保存

-## 架构说明
+2. **开始对话**
+   - 输入消息
+   - 按 Enter 发送
+   - 查看工具调用和AI响应

- **无上下文**: 每次请求仅带当前输入，不含历史消息
- **图数据库**: 所有记忆存储在 Neo4j 图中
- **自主决策**: 模型自主判断何时查询/写入记忆
+3. **快捷键**
+   - F1: 帮助
+   - F2: 切换侧边栏
+   - F3: 工具详情
+   - F5: 清屏
+   - F6: 退出

-## 文件结构
+---

-```
-.
-├── graph_memory_demo.py     # 主程序
-├── scripts/                # 各发行版安装脚本
-│   ├── install_neo4j_ubuntu.sh
-│   ├── install_neo4j_centos.sh
-│   ├── install_neo4j_openeuler.sh
-│   └── start_neo4j_docker.sh
-├── docker/                 # Docker 部署
-│   ├── docker-compose.yml
-│   ├── start.sh
-│   └── .env.example
-└── README.md
-```
+## 工具说明

-## Neo4j 配置
+系统向模型暴露 6 个记忆管理工具，由模型根据对话需求自主调用。

- HTTP: http://localhost:7474
- Bolt: bolt://localhost:7687
- 用户: neo4j / (设置密码)
+| 工具名 | 描述 | 关键参数 |
+|--------|------|----------|
+| memory_recall | 检索相关子图 | query_intent (str): 关键词意图<br>seed_entities (List[str]): 起始实体<br>depth (int): 遍历深度<br>time_range (str, 可选): 时间范围 |
+| memory_commit | 写入三元组 | triplets (List[Dict]): 每项含 subject, relation, object, confidence (float, 0.0-1.0) |
+| memory_purge | 删除或替代记忆 | criteria (Dict): 匹配条件<br>mode (str): soft / supersede<br>new_relation (Dict, 可选): 替代关系 |
+| memory_introspect | 查看当前会话元数据 | session_id (str, 可选) |
+| memory_archive | 归档旧关系 | days (int): 归档天数阈值 |
+| memory_cleanup | 物理清理已删除数据 | dry_run (bool): 预览模式 |

-## 测试验证
+---

-```bash
-# 测试 Neo4j 连接
-cypher-shell -u neo4j -p your_password "MATCH (n) RETURN count(n)"
-```
+## 图数据库模式
+
+### 节点（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 的记忆方式，更像人。**