diff --git a/README.md b/README.md index ccefe40..1a1ad9b 100644 --- a/README.md +++ b/README.md @@ -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): 关键词意图
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) - ---- - -## 贡献 - -欢迎任何形式的贡献！请先阅读贡献指南。 +- **Python 3.8+** - 编程语言 +- **Textual** - TUI框架 +- **SQLite** - 内嵌数据库 +- **Flask** - Web框架 +- **OpenAI SDK** - API调用 --- ## 许可证 -本项目采用 MIT License。 +MIT License + +--- + +## 贡献 + +欢迎提交Issue和Pull Request！ --- diff --git a/docs/API配置指南.md b/docs/API配置指南.md deleted file mode 100644 index ac80b89..0000000 --- a/docs/API配置指南.md +++ /dev/null @@ -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 对话 -- ✅ 使用图数据库记忆 -- ✅ 执行工具调用 -- ✅ 管理长期记忆 - -开始你的图记忆对话之旅吧！ - -🎯 diff --git a/docs/一键启动指南.md b/docs/一键启动指南.md index 790f97e..f916edb 100644 --- a/docs/一键启动指南.md +++ b/docs/一键启动指南.md @@ -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退出 + +开始使用吧！ diff --git a/docs/打包说明.md b/docs/打包说明.md deleted file mode 100644 index 154ff92..0000000 --- a/docs/打包说明.md +++ /dev/null @@ -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 -``` - -🎯 diff --git a/docs/数据库测试报告.md b/docs/数据库测试报告.md deleted file mode 100644 index 9897b8b..0000000 --- a/docs/数据库测试报告.md +++ /dev/null @@ -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! ✅ -``` - -🎯 diff --git a/docs/项目结构.md b/docs/项目结构.md deleted file mode 100644 index d4f03ab..0000000 --- a/docs/项目结构.md +++ /dev/null @@ -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 -```