jianf/TrulyMEM-TrueHumanMEM
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/TrulyMEM-TrueHumanMEM.git synced 2026-09-23 02:18:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update README and clean up documentation

Browse Source 
- Rewrite README with clear structure
- Remove redundant documentation files
- Update startup guide
- Add API documentation
- Add FAQ section
- Simplify project structure
This commit is contained in:
JianFeeeee
2026-04-10 15:55:07 +08:00
parent 46c58bccc5
commit e9df29a988
6 changed files with 306 additions and 1124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

485
README.md
View File

@ -4,127 +4,24 @@
一个让 AI 拥有自知、可塑、有分寸感长期记忆的图记忆系统，配备现代化终端用户界面。
## ✨ 特性
- 🖥️ **现代化TUI界面** - 基于Textual框架的终端界面
- 💾 **内嵌数据库** - SQLite实现，无需Docker/Neo4j
- 🌐 **Web接口** - 支持浏览器访问
- 🚀 **一键启动** - 3步骤完成，30秒启动
- 🌍 **跨平台** - 支持Windows/Linux/macOS
- 📊 **实时可视化** - 消息、工具调用实时显示
- 🔧 **完整功能** - 记忆检索、写入、删除、归档
## 📖 目录
- [背景与理念](#背景与理念)
- [核心特性](#核心特性)
- [架构设计](#架构设计)
- [快速开始](#快速开始)
- [工具说明](#工具说明)
- [图数据库模式](#图数据库模式)
- [与传统方案的对比](#与传统方案的对比)
- [路线图](#路线图)
- [限制与注意事项](#限制与注意事项)
---
## 背景与理念
### 传统 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 图数据库 │
│ (实体节点 + 关系边) │
└─────────────────────────┘
```
- **轻量级上下文**：每轮仅包含系统提示、上一轮工具调用结果、当前用户输入。过往对话历史不累积。
- **持续工具调用循环**：模型可在一次回复中调用多个工具，直至给出最终文本回复。
- **可观测性支持**：所有工具调用记录于会话日志，支持审计追踪与调试回溯。
- [使用方法](#使用方法)
- [功能说明](#功能说明)
- [API接口](#api接口)
- [配置说明](#配置说明)
- [开发指南](#开发指南)
---
@ -133,10 +30,9 @@ TrueHumanMEM 不是更强大的搜索引擎，而是更像人的记忆伙伴。
### 前置要求
- **Python 3.8+**
- **Docker** (用于 Neo4j 数据库)
- **DeepSeek API Key**（或兼容 OpenAI 格式的任意 LLM API）
- **DeepSeek API Key**（或兼容OpenAI格式的API）
### 一键启动（推荐）
### 一键启动
#### Windows
```bash
@ -157,188 +53,227 @@ chmod +x start.sh
python3 start.py
```
启动脚本会自动：
1. ✅ 启动 Docker (优先WSL，回退到Docker Desktop)
2. ✅ 启动 Neo4j 数据库
3. ✅ 创建虚拟环境
4. ✅ 安装依赖
5. ✅ 启动 TUI 应用
### 启动流程
### 手动启动
```
[Step 1/3] 检查 Python
[Step 2/3] 设置虚拟环境
[Step 3/3] 启动应用
#### 1. 克隆仓库
```bash
git clone https://github.com/your-org/TrueHumanMEM.git
cd TrueHumanMEM
✅ 系统初始化成功！
• 数据库: 内嵌SQLite (graph_memory.db)
• API Key: 未配置
```
#### 2. 安装依赖
---
## 使用方法
### 1. 配置 API Key
1. 按 **F2** 展开侧边栏
2. 点击 **"配置"**
3. 输入你的 **DeepSeek API Key**
4. 按 **Enter** 保存
### 2. 开始对话
- 输入消息
- 按 **Enter** 发送
- 查看AI响应和工具调用
### 3. 快捷键
| 快捷键 | 功能 |
|--------|------|
| F1 | 帮助 |
| F2 | 切换侧边栏 |
| F3 | 工具详情 |
| F4 | 查询框 |
| F5 | 清屏 |
| F6 | 退出 |
---
## 功能说明
### 记忆管理工具
| 工具 | 功能 | 参数 |
|------|------|------|
| memory_recall | 检索记忆 | query_intent, depth |
| memory_commit | 写入记忆 | triplets, confidence |
| memory_purge | 删除记忆 | criteria, mode |
| memory_introspect | 查看状态 | - |
| memory_archive | 归档记忆 | days |
| memory_cleanup | 清理数据 | dry_run |
### 数据库
**内嵌SQLite数据库：**
- 文件：`graph_memory.db`
- 无需配置
- 自动创建
- 本地存储
**数据结构：**
- 实体（entities）：name, type, mention_count
- 关系（relations）：source, target, type, confidence, status
---
## API接口
### Web接口
启动后访问：`http://localhost:5000`
### REST API
```bash
# 检索记忆
POST /api/memory/recall
{
"query_intent": "Python,AI"
}
# 写入记忆
POST /api/memory/commit
{
"triplets": [
{"subject": "用户", "relation": "喜欢", "object": "Python"}
]
}
# 查看状态
GET /api/memory/introspect
# 获取配置
GET /api/config
```
---
## 配置说明
### 环境变量
创建 `.env` 文件：
```bash
# API配置
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat
# 数据库配置（可选）
USE_EMBEDDED_DB=true
```
### 切换数据库
**使用内嵌数据库（默认）：**
```bash
USE_EMBEDDED_DB=true
```
**使用Neo4j（需要Docker）：**
```bash
USE_EMBEDDED_DB=false
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=graphmemory123
```
---
## 开发指南
### 项目结构
```
graph_enable_ability/
├── graph_memory_tui/ # TUI应用
│ ├── core/ # 核心逻辑
│ │ ├── embedded_db.py # 内嵌数据库
│ │ └── imports.py
│ ├── web/ # Web接口
│ ├── widgets/ # UI组件
│ ├── styles/ # 样式
│ └── app.py
├── tests/ # 测试
├── docs/ # 文档
├── start.bat # Windows启动
├── start.sh # Linux/macOS启动
└── start.py # 跨平台启动
```
### 运行测试
```bash
# 安装依赖
pip install -r requirements.txt
# 运行测试
pytest tests/
```
#### 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"
```
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
#### 5. 运行应用
# 安装依赖
pip install -r requirements.txt
**TUI 界面（推荐）**
```bash
# 运行应用
python -m graph_memory_tui.main
```
**命令行 Demo**
```bash
python graph_memory_demo.py
```
---
### 使用 TUI 界面
## 常见问题
1. **配置 API Key**
- 按 F2 展开侧边栏
- 点击"配置"
- 输入你的 DeepSeek API Key
- 按 Enter 保存
### Q: 启动时显示"API Key 未配置"？
2. **开始对话**
- 输入消息
- 按 Enter 发送
- 查看工具调用和AI响应
**A:** 按F2打开侧边栏，在配置区输入API Key，按Enter保存。
3. **快捷键**
- F1: 帮助
- F2: 切换侧边栏
- F3: 工具详情
- F5: 清屏
- F6: 退出
### Q: 数据保存在哪里？
**A:** 数据保存在 `graph_memory.db` 文件中，可以备份或迁移。
### Q: 如何查看数据库内容？
**A:** 使用SQLite工具打开 `graph_memory.db`，或使用 `memory_introspect` 工具。
### Q: 支持哪些API？
**A:** 支持所有兼容OpenAI格式的API，如DeepSeek、OpenAI等。
---
## 工具说明
## 技术栈
系统向模型暴露 6 个记忆管理工具，由模型根据对话需求自主调用。
| 工具名 | 描述 | 关键参数 |
|--------|------|----------|
| 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): 预览模式 |
---
## 图数据库模式
### 节点（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)
---
## 贡献
欢迎任何形式的贡献！请先阅读贡献指南。
- **Python 3.8+** - 编程语言
- **Textual** - TUI框架
- **SQLite** - 内嵌数据库
- **Flask** - Web框架
- **OpenAI SDK** - API调用
---
## 许可证
本项目采用 MIT License。
MIT License
---
## 贡献
欢迎提交Issue和Pull Request！
---

243
docs/API配置指南.md
View File

@ -1,243 +0,0 @@
# API Key 配置指南
## ❌ 连接错误原因
**错误信息：** `Connection error`
**可能原因：**
1. ❌ API Key 未配置
2. ❌ API Key 无效
3. ❌ 网络无法访问 API
4. ❌ API 服务器暂时不可用
## ✅ 解决方法
### 方法1：在 TUI 中配置（推荐）
**步骤：**
1. **按 F2** - 展开右侧边栏
2. **点击"配置"** - 展开配置区域
3. **输入 API Key** - 在输入框输入你的密钥
4. **按 Tab** - 保存并应用
**详细操作：**
```
启动应用
↓
看到欢迎消息
↓
按 F2 键
↓
右侧出现侧边栏
↓
点击"配置"标题
↓
看到三个输入框：
┌─────────────────────┐
│ API Key: │
│ [******************]│ ← 输入你的 Key
│ │
│ 模型: │
│ [deepseek-chat ] │
│ │
│ Base URL: │
│ [https://api... ]│
└─────────────────────┘
↓
输入 API Key: sk-xxxxxxxxxxxxx
↓
按 Tab 键
↓
看到通知："✅ 配置已更新并应用"
↓
配置完成！
```
### 方法2：环境变量配置
**Windows:**
```cmd
setx DEEPSEEK_API_KEY "sk-xxxxxxxxxxxxx"
```
**Linux/macOS:**
```bash
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxx"
```
**注意：** 设置环境变量后需要重启终端。
### 方法3：配置文件
**创建配置文件：**
**Windows:**
```
C:\Users\<你的用户名>\.graph_memory_tui\config.json
```
**Linux/macOS:**
```
~/.graph_memory_tui/config.json
```
**文件内容：**
```json
{
"api_key": "sk-xxxxxxxxxxxxx",
"model": "deepseek-chat",
"base_url": "https://api.deepseek.com"
}
```
## 🔑 获取 API Key
### DeepSeek API Key
1. 访问：https://platform.deepseek.com/
2. 注册/登录账号
3. 进入 API Keys 页面
4. 创建新的 API Key
5. 复制密钥（以 `sk-` 开头）
### 其他兼容 API
如果使用其他 OpenAI 兼容 API：
- 修改 Base URL
- 使用对应的 API Key
## 🧪 验证配置
### 测试步骤
1. **配置 API Key** - 按上述方法配置
2. **发送测试消息** - 输入"你好"
3. **查看响应** - 应该收到 AI 回复
### 成功标志
```
✅ 配置已更新并应用
[你的消息] 你好
[AI回复] 你好！我是图数据库记忆助手...
```
### 失败标志
```
❌ 错误: Connection error
网络连接错误！可能的原因：
1. API Key 未配置或无效
2. 网络无法访问 API 服务器
...
```
## 🔧 故障排除
### 问题1：API Key 格式错误
**检查：**
- ✅ 以 `sk-` 开头
- ✅ 没有空格
- ✅ 完整复制
**示例：**
```
✅ sk-1234567890abcdef...
❌ 1234567890abcdef... (缺少 sk- 前缀)
❌ sk-1234 5678... (包含空格)
```
### 问题2：网络问题
**检查：**
- 网络连接是否正常
- 能否访问 https://api.deepseek.com
- 是否需要代理/VPN
**测试网络：**
```bash
curl https://api.deepseek.com/v1/models
```
### 问题3：API Key 无效
**检查：**
- API Key 是否过期
- 账号是否有余额
- 是否有权限访问 API
**解决：**
- 重新生成 API Key
- 检查账号状态
- 充值或升级套餐
### 问题4：配置未生效
**检查：**
- 是否按 Tab 保存
- 是否看到配置更新通知
- 重启应用测试
**解决：**
- 重新配置
- 检查配置文件
- 清除缓存重试
## 📊 配置优先级
1. **TUI 页面配置**（最高优先级）
- 实时生效
- 自动保存
2. **环境变量**
- 全局生效
- 需要重启终端
3. **配置文件**
- 持久化保存
- 自动加载
## 💡 最佳实践
### 安全建议
- ✅ 不要分享 API Key
- ✅ 定期更换密钥
- ✅ 使用环境变量或配置文件
- ❌ 不要在代码中硬编码
- ❌ 不要提交到版本控制
### 使用建议
- ✅ 使用 TUI 配置（最方便）
- ✅ 配置后立即测试
- ✅ 保存配置文件备份
- ✅ 记录 API Key 获取日期
## 🎯 快速配置清单
- [ ] 获取 API Key
- [ ] 启动应用
- [ ] 按 F2 展开侧边栏
- [ ] 点击"配置"
- [ ] 输入 API Key
- [ ] 按 Tab 保存
- [ ] 发送测试消息
- [ ] 验证响应正常
## 🎉 配置成功后
你就可以：
- ✅ 与 AI 对话
- ✅ 使用图数据库记忆
- ✅ 执行工具调用
- ✅ 管理长期记忆
开始你的图记忆对话之旅吧！
🎯

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

@ -1,252 +1,164 @@
baoliu1# Graph Memory TUI - 一键启动指南
# 一键启动指南
## 🚀 快速开始
### Windows
**方法 1: 双击启动（推荐）**
```
```bash
# 方法1: 双击运行
双击 start.bat
```
**方法 2: 命令行启动**
```bash
# 方法2: 命令行
start.bat
```
**方法 3: Python启动**
```bash
# 方法3: Python
python start.py
```
### Linux / macOS
**方法 1: Shell脚本**
```bash
# 方法1: Shell脚本
chmod +x start.sh
./start.sh
```
**方法 2: Python启动**
```bash
# 方法2: Python
python3 start.py
```
## 📋 一键启动脚本功能
## 📋 启动流程
启动脚本会自动完成以下步骤：
```
[Step 1/3] 检查 Python
↓
[Step 2/3] 设置虚拟环境
- 创建venv（如果不存在）
- 安装依赖
↓
[Step 3/3] 启动应用
↓
✅ 系统初始化成功！
```
### Step 1: 启动 Docker
- ✅ 检查 Docker 是否安装
- ✅ 自动启动 Docker Desktop (Windows) / Docker daemon (Linux/macOS)
- ✅ 等待 Docker 就绪（最多60秒）
## ⏱️ 启动时间
### Step 2: 启动 Neo4j
- ✅ 检查 Neo4j 容器是否存在
- ✅ 自动创建容器（如果不存在）
- ✅ 启动 Neo4j 数据库
- ✅ 等待数据库就绪
### Step 3: 检查 Python
- ✅ 验证 Python 版本
- ✅ 显示 Python 信息
### Step 4: 设置虚拟环境
- ✅ 创建虚拟环境（如果不存在）
- ✅ 激活虚拟环境
- ✅ 安装依赖包
### Step 5: 启动应用
- ✅ 启动 Graph Memory TUI
- ✅ 显示连接信息
- **首次启动**: 约1-2分钟（安装依赖）
- **后续启动**: 约30秒
## 🔧 系统要求
### 必需软件
### 必需
1. **Docker Desktop**
- Windows: https://www.docker.com/products/docker-desktop
- Linux: https://docs.docker.com/get-docker/
- macOS: https://docs.docker.com/docker-for-mac/install/
- **Python 3.8+**
- **DeepSeek API Key**
2. **Python 3.8+**
- https://www.python.org/downloads/
### 可选
### 硬件要求
- **Git** - 用于克隆仓库
- 内存: 至少 4GB (推荐 8GB)
- 磁盘: 至少 5GB 可用空间
- CPU: 2核心以上
## 📝 首次使用
## 📊 启动流程
### 1. 启动应用
```
start.bat / start.sh / start.py
↓
[1/5] 检查 Docker
↓
[2/5] 启动 Neo4j
↓
[3/5] 检查 Python
↓
[4/5] 设置虚拟环境
↓
[5/5] 启动应用
↓
Graph Memory TUI 运行中
```bash
start.bat # Windows
./start.sh # Linux/macOS
```
## 🎯 使用方法
### 2. 配置 API Key
### 首次启动
1. 按 **F2** 展开侧边栏
2. 点击 **"配置"**
3. 输入 **DeepSeek API Key**
4. 按 **Enter** 保存
1. **双击 `start.bat` (Windows) 或运行 `./start.sh` (Linux/macOS)**
### 3. 开始对话
2. **等待所有步骤完成**（约1-2分钟）
- 输入消息
- 按 **Enter** 发送
3. **看到以下信息表示成功：**
```
========================================
All systems ready!
========================================
Neo4j Connection:
- Browser: http://localhost:7474
- Bolt: bolt://localhost:7687
- User: neo4j
- Pass: graphmemory123
Starting TUI application...
```
## 🌐 获取 API Key
4. **配置 API Key**
- 按 F2 展开侧边栏
- 点击"配置"
- 输入你的 DeepSeek API Key
- 按 Enter 保存
### DeepSeek
5. **开始对话**
- 输入消息
- 按 Enter 发送
1. 访问：https://platform.deepseek.com/
2. 注册账号
3. 创建 API Key
4. 复制密钥
### 后续启动
### 其他兼容API
直接运行启动脚本即可，所有服务会自动启动。
- OpenAI
- 其他兼容OpenAI格式的API
## ⚠️ 常见问题
### 问题 1: Docker 启动失败
### Q: Python 未找到
**错误：** `Docker Desktop failed to start`
**A:** 安装 Python 3.8+
- Windows: https://www.python.org/downloads/
- Linux: `sudo apt install python3`
- macOS: `brew install python3`
**解决：**
1. 手动启动 Docker Desktop
2. 等待 Docker 完全启动（托盘图标显示绿色）
3. 重新运行启动脚本
### Q: 依赖安装失败
### 问题 2: Neo4j 连接失败
**错误：** `Couldn't connect to localhost:7687`
**解决：**
**A:** 手动安装
```bash
# 检查容器状态
docker ps -a | grep neo4j
# 重启容器
docker restart neo4j
# 查看日志
docker logs neo4j
```
### 问题 3: Python 依赖安装失败
**错误：** `Failed to install dependencies`
**解决：**
```bash
# 手动安装
python -m venv venv
venv\Scripts\activate # Windows
source venv/bin/activate # Linux/macOS
pip install -r requirements.txt
```
### 问题 4: 端口被占用
### Q: API Key 无效
**错误：** `port 7474 or 7687 already in use`
**A:** 检查API Key格式
- 应以 `sk-` 开头
- 无多余空格
- 正确复制
**解决：**
```bash
# 停止旧容器
docker stop neo4j
docker rm neo4j
## 🎯 快捷键
# 重新运行启动脚本
```
| 快捷键 | 功能 |
|--------|------|
| F1 | 帮助 |
| F2 | 侧边栏 |
| F3 | 工具详情 |
| F5 | 清屏 |
| F6 | 退出 |
## 🌐 访问 Neo4j 浏览器
## 📊 数据存储
启动成功后，可以访问 Neo4j 浏览器界面：
- **数据库**: `graph_memory.db`
- **位置**: 应用目录
- **格式**: SQLite
- **可备份**: 是
1. 打开浏览器访问: http://localhost:7474
2. 登录信息:
- 用户名: `neo4j`
- 密码: `graphmemory123`
## 📝 配置文件
### 环境变量
创建 `.env` 文件配置：
## 🔄 更新应用
```bash
# API配置
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat
# 拉取最新代码
git pull
# Neo4j配置
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=graphmemory123
```
## 🔄 停止服务
### 停止应用
- 按 F6 或 Ctrl+C
### 停止 Neo4j
```bash
docker stop neo4j
```
### 停止 Docker Desktop
- Windows: 右键托盘图标 → Quit Docker Desktop
- Linux: `sudo systemctl stop docker`
- macOS: 右键托盘图标 → Quit Docker
## 📚 更多信息
- 架构设计: `架构.md`
- API文档: `specs/` 目录
- 问题反馈: GitHub Issues
## 🎉 开始使用
现在就运行启动脚本，开始使用 Graph Memory TUI 吧！
```bash
# Windows
# 重新启动
start.bat
# Linux/macOS
./start.sh
# 或使用 Python
python start.py
```
🎯
## 🗑️ 清理数据
```bash
# 删除数据库
rm graph_memory.db
# 重新启动会创建新数据库
start.bat
```
## 💡 提示
- 首次启动需要安装依赖，请耐心等待
- API Key 只需配置一次
- 数据自动保存，无需手动操作
- 可以随时按F6退出
开始使用吧！

132
docs/打包说明.md
View File

@ -1,132 +0,0 @@
a# 打包说明
## 🎯 打包为可执行文件
### 方法1: 使用打包脚本（推荐）
```bash
# 安装PyInstaller
pip install pyinstaller
# 运行打包脚本
python build.py
```
打包完成后，会在 `dist/` 目录生成：
- `GraphMemoryTUI.exe` - 可执行文件
### 方法2: 手动打包
```bash
# 安装PyInstaller
pip install pyinstaller
# 打包为单个可执行文件
pyinstaller graph_memory_tui/main.py \
--name=GraphMemoryTUI \
--onefile \
--windowed \
--add-data="graph_memory_tui/styles;graph_memory_tui/styles" \
--hidden-import=textual \
--hidden-import=neo4j \
--hidden-import=openai
```
## 📦 打包选项说明
| 选项 | 说明 |
|------|------|
| --onefile | 打包为单个可执行文件 |
| --windowed | 无控制台窗口 |
| --add-data | 添加数据文件 |
| --hidden-import | 添加隐式导入 |
| --exclude-module | 排除模块 |
## 🚀 使用打包后的应用
### 直接运行
1. 双击 `GraphMemoryTUI.exe`
2. 应用会自动启动
3. 无需Python环境
### 分发给他人
1. 将 `GraphMemoryTUI.exe` 复制给他人
2. 对方直接双击运行
3. 无需安装任何依赖
## 📋 注意事项
### 首次运行
首次运行时，需要：
1. 启动Docker
2. 启动Neo4j
3. 配置API Key
### 系统要求
- Windows 10/11
- Docker Desktop（或WSL2 + Docker）
- 至少4GB内存
### 文件大小
打包后的可执行文件约：
- 50-100MB（包含所有依赖）
## 🔧 创建安装程序
### 使用Inno Setup
1. 安装 [Inno Setup](https://jrsoftware.org/isinfo.php)
2. 运行 `build.py` 并选择创建安装程序
3. 编译生成的 `setup.iss`
4. 生成 `GraphMemoryTUI-Setup.exe`
### 安装程序功能
- ✅ 自动安装应用
- ✅ 创建桌面快捷方式
- ✅ 创建开始菜单项
- ✅ 包含文档
- ✅ 支持卸载
## 📊 对比
| 方式 | 优点 | 缺点 |
|------|------|------|
| Python源码 | 灵活、可修改 | 需要Python环境 |
| 可执行文件 | 无需Python、易分发 | 文件较大、不可修改 |
| 安装程序 | 专业、完整 | 需要额外工具 |
## 💡 建议
**开发阶段：**
- 使用Python源码运行
- 方便调试和修改
**分发给用户：**
- 打包为可执行文件
- 或创建安装程序
- 提供完整的使用说明
## 🎉 开始打包
```bash
# 1. 安装依赖
pip install -r requirements.txt
pip install pyinstaller
# 2. 运行打包
python build.py
# 3. 测试可执行文件
dist/GraphMemoryTUI.exe
# 4. 分发给他人
# 复制 dist/GraphMemoryTUI.exe
```
🎯

174
docs/数据库测试报告.md
View File

@ -1,174 +0,0 @@
# 内嵌数据库测试报告
## 测试概览
**测试时间：** 2026-04-10
**测试对象：** EmbeddedGraphDB (SQLite实现)
**测试结果：** ✅ 全部通过 (15/15)
## 测试详情
### ✅ Test 1: 写入记忆 (Commit Memory)
- **功能：** 写入三元组数据
- **输入：** 4条关系，包含实体类型和置信度
- **结果：** 成功创建8个实体，4条关系
- **状态：** PASS
### ✅ Test 2: 单关键词检索 (Recall - Single Keyword)
- **功能：** 使用单个关键词检索
- **输入：** "Python"
- **结果：** 找到1个实体，2条关系
- **状态：** PASS
### ✅ Test 3: 多关键词检索 (Recall - Multiple Keywords)
- **功能：** 使用多个关键词检索
- **输入：** "Python,AI,用户"
- **结果：** 找到3个实体，4条关系
- **状态：** PASS
### ✅ Test 4: 会话过滤 (Session Filter)
- **功能：** 按会话ID过滤检索结果
- **输入：** session_id="test-session-001"
- **结果：** 只返回该会话的关系
- **状态：** PASS
### ✅ Test 5: 查看状态 (Introspect)
- **功能：** 查看数据库统计信息
- **结果：** 正确返回实体数和关系数
- **状态：** PASS
### ✅ Test 6: 软删除 (Purge - Soft Delete)
- **功能：** 标记关系为deleted状态
- **输入：** criteria={"source": "用户", "relation": "喜欢"}
- **结果：** 成功删除1条关系
- **状态：** PASS
### ✅ Test 7: 添加更多数据 (Add More Data)
- **功能：** 继续添加数据
- **结果：** 成功添加新数据
- **状态：** PASS
### ✅ Test 8: 归档 (Archive)
- **功能：** 归档旧关系
- **输入：** days=0 (归档所有)
- **结果：** 归档功能正常
- **状态：** PASS
### ✅ Test 9: 清理预览 (Cleanup - Dry Run)
- **功能：** 预览将要删除的数据
- **输入：** dry_run=True
- **结果：** 返回预览信息，不实际删除
- **状态：** PASS
### ✅ Test 10: 实际清理 (Cleanup - Execute)
- **功能：** 执行实际清理
- **输入：** dry_run=False
- **结果：** 清理功能正常
- **状态：** PASS
### ✅ Test 11: 约束检查 (Ensure Constraints)
- **功能：** 确保数据库约束
- **结果：** 无错误执行
- **状态：** PASS
### ✅ Test 12: 重复实体处理 (Duplicate Entity Handling)
- **功能：** 处理重复实体
- **输入：** 再次添加"用户学习Python"
- **结果：** mention_count增加，不创建重复实体
- **状态：** PASS
### ✅ Test 13: 空查询 (Empty Query)
- **功能：** 处理空查询
- **输入：** query_intent=""
- **结果：** 返回空结果，不报错
- **状态：** PASS
### ✅ Test 14: 不存在的实体 (Non-existent Entity)
- **功能：** 查询不存在的实体
- **输入：** "不存在的实体xyz123"
- **结果：** 返回空结果，不报错
- **状态：** PASS
### ✅ Test 15: 硬删除 (Purge - Hard Delete)
- **功能：** 物理删除关系
- **输入：** criteria={"relation": "是"}, mode="hard"
- **结果：** 成功删除2条关系
- **状态：** PASS
## 功能覆盖
| 功能 | 测试状态 | 备注 |
|------|---------|------|
| 写入记忆 | ✅ PASS | 支持三元组、置信度、实体类型 |
| 检索记忆 | ✅ PASS | 支持单/多关键词、会话过滤 |
| 软删除 | ✅ PASS | 标记为deleted状态 |
| 硬删除 | ✅ PASS | 物理删除 |
| 归档 | ✅ PASS | 按时间归档 |
| 清理 | ✅ PASS | 支持预览和执行 |
| 状态查看 | ✅ PASS | 返回统计信息 |
| 约束检查 | ✅ PASS | 兼容接口 |
| 重复处理 | ✅ PASS | 自动去重 |
| 异常处理 | ✅ PASS | 空查询、不存在实体 |
## 性能测试
| 操作 | 数据量 | 耗时 |
|------|--------|------|
| 写入 | 4条关系 | <10ms |
| 检索 | 3个关键词 | <5ms |
| 删除 | 1条关系 | <5ms |
| 归档 | 全部 | <5ms |
| 清理 | 预览 | <5ms |
## 兼容性测试
### ✅ 接口兼容性
- `recall()` - 完全兼容Neo4j接口
- `commit()` - 完全兼容Neo4j接口
- `purge()` - 完全兼容Neo4j接口
- `introspect()` - 完全兼容Neo4j接口
- `archive()` - 完全兼容Neo4j接口
- `cleanup()` - 完全兼容Neo4j接口
- `ensure_constraints()` - 完全兼容Neo4j接口
### ✅ 数据格式兼容性
- 实体格式：`{name, type, mention_count}`
- 关系格式：`{source, target, type, confidence, ...}`
- 返回格式：与Neo4j完全一致
## 结论
### ✅ 测试通过率：100% (15/15)
### 功能完整性
- ✅ 所有核心功能正常
- ✅ 所有接口兼容
- ✅ 所有异常处理正确
### 数据正确性
- ✅ 写入数据正确
- ✅ 检索结果正确
- ✅ 删除操作正确
- ✅ 统计信息正确
### 性能表现
- ✅ 操作响应快速 (<10ms)
- ✅ 无明显性能问题
- ✅ 适合中小规模数据
### 建议
1. **可以使用** - 功能完整，测试通过
2. **适合场景** - 开发、测试、个人使用
3. **注意事项** - 大规模数据建议使用Neo4j
## 测试命令
```bash
# 运行完整测试
python test_embedded_db.py
# 测试结果
# All Tests Passed! ✅
```
🎯

116
docs/项目结构.md
View File

@ -1,116 +0,0 @@
# 项目结构
```
graph_enable_ability/
├── docs/ # 文档目录
│ ├── 架构.md # 架构设计文档
│ ├── 一键启动指南.md # 启动脚本使用指南
│ └── API配置指南.md # API Key配置说明
│
├── graph_memory_tui/ # TUI应用主目录
│ ├── widgets/ # UI组件
│ ├── models/ # 数据模型
│ ├── core/ # 核心逻辑
│ ├── styles/ # 样式文件
│ └── app.py # 主应用
│
├── tests/ # 测试目录
├── scripts/ # 脚本目录
├── docker/ # Docker配置
│
├── graph_memory_demo.py # 命令行Demo
├── start.bat # Windows启动脚本
├── start.sh # Linux/macOS启动脚本
├── start.py # 跨平台Python启动脚本
├── start_neo4j.bat # Neo4j启动脚本
├── quick_start.bat # 快速启动脚本
│
├── requirements.txt # Python依赖
├── README.md # 项目说明
└── 图数据库结构设计 # 数据库设计文档
```
## 核心文件说明
### 启动脚本
- **start.bat** - Windows一键启动脚本
- 自动启动Docker (优先WSL)
- 自动启动Neo4j
- 自动安装依赖
- 启动TUI应用
- **start.sh** - Linux/macOS启动脚本
- 功能同start.bat
- 支持systemctl启动Docker
- **start.py** - 跨平台Python启动脚本
- 自动检测系统语言
- 自动选择最佳Docker启动方式
- 支持Windows/Linux/macOS
### 应用文件
- **graph_memory_tui/** - TUI应用目录
- 基于Textual框架
- 现代化终端界面
- 实时消息显示
- 工具调用可视化
- **graph_memory_demo.py** - 命令行Demo
- 简单的命令行界面
- 用于测试和调试
### 文档
- **docs/** - 文档目录
- 架构设计
- 使用指南
- 配置说明
- **README.md** - 项目主文档
- 项目介绍
- 快速开始
- 功能说明
## 使用流程
1. **首次使用**
```bash
# Windows
start.bat
# Linux/macOS
./start.sh
```
2. **配置API Key**
- 按F2打开侧边栏
- 输入API Key
- 按Enter保存
3. **开始对话**
- 输入消息
- 按Enter发送
- 查看响应
## 开发相关
### 运行测试
```bash
python run_tests.py
```
### 安装依赖
```bash
pip install -r requirements.txt
```
### 手动启动Neo4j
```bash
# Windows
start_neo4j.bat
# Linux/macOS
docker start neo4j
```