Memora - 个人 AI 知识库

Memora 是一个自托管的个人 AI 知识库系统，提供从知识捕获到智能问答的一体化体验。基于向量检索、混合搜索和大语言模型驱动的智能组织，帮助您高效管理、检索并利用个人知识资产。

版本历史

v2.0.5（当前版本）

• 📝 完整重写 SKILL.md：更新 OpenClaw 技能定义，包含完整产品概述
• 🎨 知识图谱 v2.0：预览 + 全屏模态架构
• 🖱️ 增强交互体验：支持缩放、平移、拖拽、悬停查看详情
• 居中布局：使用力导向算法实现以原点为中心的定位
• 🔄 智能缓存机制：预览数据已缓存，模态框使用更大数据集
• 双视图模式：文档关系图 + 实体关系图
• 依赖包更新：修复 package.json 版本不匹配问题

v2.0.4

• 📝 完整产品文档：包含完整产品概述的详细 README
• 🎨 知识图谱 v2.0：预览 + 全屏模态架构
• 🖱️ 增强交互体验：支持缩放、平移、拖拽、悬停查看详情
• 🎯 居中布局：使用力导向算法实现以原点为中心的定位
• 🔄 智能缓存机制：预览数据已缓存，模态框使用更大数据集
• 双视图模式：文档关系图 + 实体关系图

v2.0.0

• 初始版本，支持知识图谱可视化
• 基于力导向布局的交互式控制
• Obsidian 风格视觉设计

核心功能

🔐 隐私与本地部署

• 完全私密：数据本地存储，不上传至第三方
• 离线可用：无需互联网连接即可运行
• 单用户模式：无需认证，开箱即用

智能语义检索

• 混合搜索：密集向量 + BM42 稀疏向量双引擎检索
• 相关性重排序：可选重排序模型进行二次排序
• 降级机制：自动切换至备用策略
• 语义理解：基于向量相似度，非关键词匹配

📄 多格式文档处理

• 支持格式：PDF、Word（.docx/.doc）、纯文本（.txt）、Markdown（.md）
• 智能分块：使用 LangChain 递归字符分割器，支持中英文
• 向量存储：密集向量与稀疏向量存储于 Qdrant
• 元数据管理：支持标签和自定义元数据用于分类组织

AI 驱动的问答

• 两种交互模式：

- 知识查询：基于检索结果生成精准问答

- 知识组织：由 LLM 自动整理并总结知识内容

• 流式输出：实时生成内容
• 会话管理：支持多轮对话并保留历史记录
• 来源标注：回答中包含源文档链接

🕸️ 知识图谱可视化

• 力导向布局：自动节点定位，形成自然网络结构
• 双视图展示：文档关系图 + 实体关系图
• 交互操作：

- 鼠标滚轮缩放（以光标为中心）

- 拖动空白区域平移画布

- 拖动节点重新定位

- 悬停显示详细信息

• Obsidian 风格设计：黑色节点、白色背景、细微连接线

🌐 网页抓取与集成

• 内置爬虫：使用 httpx + BeautifulSoup，无外部依赖
• OpenClaw 集成：作为 AI Agent 技能提供，客户端零依赖
• RESTful API：便于与其他系统集成

快速开始

通过 clawhub 安装

openclaw skills install memora-knowledge-graph@2.0.4

手动安装

# 克隆仓库
git clone https://github.com/zzlzzlzzl15/Memora.git
cd Memora/personal_knowledge_base

# 运行安装脚本
./install.sh

Docker Compose 部署（推荐）

# 克隆仓库
git clone https://github.com/zzlzzlzzl15/Memora.git
cd Memora/personal_knowledge_base

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写您的 API 密钥

# 启动服务
docker-compose up -d

# 访问应用
# 在浏览器中打开 http://localhost:8080

配置

将 KB_API_BASE 环境变量设置为指向您的 Memora 后端：

export KB_API_BASE=http://127.0.0.1:8080

或创建 .env 文件：

KB_API_BASE=http://127.0.0.1:8080

必需环境变量

可选环境变量

使用示例

上传文档

1. 点击左侧边栏的 “上传文档” 按钮
2. 选择文件（支持 PDF、DOCX、TXT、MD 格式）
3. 填写标题和标签（可选）
4. 点击 “上传” —— 系统将自动解析、分块并生成向量

提问

1. 在右侧聊天界面输入问题
2. 选择交互模式：

- 知识查询：获取基于检索结果的精准答案

- 知识组织：让 AI 自动整理并总结相关知识

1. 查看带来源标注的回答

浏览知识图谱

1. 点击顶部导航栏的 “知识图谱” 按钮
2. 查看两个预览卡片：

- 文档关系图：展示文档之间的关联

- 实体关系图：展示提取出的实体及其关系

1. 点击任意卡片进入全屏模态进行交互探索：

- 滚动鼠标缩放

- 拖动平移画布

- 拖动节点重新定位

- 悬停查看详细信息

文档管理

• 查看列表：在左侧边栏中查看所有文档
• 搜索：使用快速搜索功能
• 回收站：查看并管理已删除的文档（可在30天内恢复）
• 永久删除：永久移除文档及向量数据

技术架构

┌─────────────────────────────────────────┐
│           Web 浏览器                    │
│     (前端 UI - HTML/CSS/JS)         │
└──────────────┬──────────────────────────┘
               │ HTTP / WebSocket
┌──────────────▼──────────────────────────┐
│         Memora 后端                   │
│       (FastAPI / Python)                │
──────────┬──────────────┬───────────────┤
│ 文档处理 │  检索引擎    │ AI 服务        │
├──────────┼──────────────┼───────────────┤
│• PDF     │• 密集向量搜索 │• 嵌入模型      │
│  解析     │  (Dense Vector)│  (DashScope/   │
│• DOCX    │• 稀疏向量搜索 │  本地 ST)     │
│  解析     │  (BM42)      │• 大语言模型对话│
│• 文本    │• 混合搜索     │  (DeepSeek/    │
│  分块     │• 降级逻辑     │  OpenAI 兼容) │
│• 元数据   │              │• 重排序       │
│• 上传    │              │  (Qwen3)      │
│  API     │              │• 流式响应     │
│          │              │                │
└────┬─────┴──────┬───────┴───────┬───────┘
     │            │               │
┌────▼────┐ ┌────▼──────┐ ┌──────▼──────┐
│ MySQL   │ │  Qdrant   │ │ 外部 API     │
│(元数据)  │ │(向量数据库)│ │              │
│         │ │           │ │              │
│• 文档   │ │• 密集向量  │ │• DashScope   │
│• 用户   │ │  (Dense)  │ │• DeepSeek    │
│• 会话   │ │• 稀疏向量  │ │• OpenAI      │
│• 历史记录 │ │  (BM42)   │ │ 兼容         │
└─────────┘ └───────────┘ └─────────────┘

技术栈

故障排查

问题：预览卡片不显示

解决方案：检查浏览器控制台错误信息。确保在 DOM 加载完成后调用 initKnowledgeGraph()。

问题：节点未居中

解决方案：强制刷新页面（Cmd+Shift+R）。如仍无效，请清除浏览器缓存。

问题：模态框内无法拖拽/缩放

解决方案：确认已为全屏可视化组件调用 setInteractive(true)。检查控制台日志。

问题：服务无法启动

解决方案：

# 查看日志
docker-compose logs -f app

# 清理并重启
docker-compose down -v
docker-compose up -d

问题：文档上传失败

解决方案：

• 检查文件格式（仅支持 PDF、DOCX、TXT、MD）
• 检查文件大小（默认限制：10MB）
• 查看应用日志：docker-compose logs -f app

问题：无检索结果

解决方案：

• 确认文档已成功上传并完成向量化
• 尝试更换查询关键词
• 降低 QDRANT_DENSE_DEFAULT_THRESHOLD 的值

问题：大语言模型调用失败

解决方案：

# 检查 API 密钥配置
cat .env | grep API_KEY

# 测试 API 连通性
curl -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  https://api.deepseek.com/v1/chat/completions \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"test"}]}'

性能优化建议

1. 限制节点数量：预览时使用较小的节点数限制（50-80 个）
2. 缓存数据：复用已获取的数据，避免重复加载
3. 防抖窗口调整：为窗口大小调整事件添加防抖处理
4. 减少迭代次数：降低 initForceLayout() 中的 iterations 值以加快加载速度（默认值：150）
5. 优化渲染：在鼠标快速移动期间跳过渲染

浏览器兼容性

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+

所需功能：

• Canvas 2D API
• CSS backdrop-filter
• ES6+ JavaScript 特性

贡献指南

欢迎贡献！请按以下步骤操作：

1. Fork 仓库
2. 创建特性分支（git checkout -b feature/awesome-feature）
3. 修改代码
4. 提交更改（git commit -m 'Add awesome feature'）
5. 推送到分支（git push origin feature/awesome-feature）
6. 提交合并请求

支持渠道

如有问题或疑问：

• GitHub Issues：https://github.com/zzlzzlzzl15/Memora/issues
• 邮箱：support@memora.dev
• 文档：https://github.com/zzlzzlzzl15/Memora/blob/main/personal_knowledge_base/README.md

致谢

• 灵感来自 [Obsidian](https://obsidian.md/) 图谱视图
• 专为 [Memora](https://github.com/zzlzzlzzl15/Memora) 个人知识库打造
• 使用类似 D3.js 力导向布局算法
• 参考 [RAG-Anything](https://github.com/RAG-Anything/RAG-Anything) 实现多模态 RAG 架构

由 zzlzzlzzl15 ❤️ 制作

*Memora - 你的个人 AI 知识库*