surrealdb-knowledge-graph-memory

SurrealDB Knowledge Graph Memory 是一款专为AI助手设计的知识图谱记忆系统，基于SurrealDB图数据库构建，集成OpenAI嵌入模型与LLM能力，实现结构化的长期记忆管理。该技能通过MCP协议提供标准化工具接口，支持知识的存储、检索、关联发现与自动维护，适用于需要复杂记忆管理的AI应用场景。

核心用法
该技能提供四类MCP工具：knowledge_search实现基于向量化的语义搜索，knowledge_recall支持带上下文的关系回溯，knowledge_store用于存储带置信度的新事实，knowledge_stats提供图谱统计。系统通过extract-knowledge.py自动从Markdown文件提取结构化知识，使用GPT-4o-mini识别实体关系，并生成text-embedding-3-small向量索引。用户可通过CLI或Gateway UI执行维护操作，包括时间衰减计算（每月5%）、低置信度剪枝与重复事实合并。

显著优点
相比简单键值存储，该系统采用图结构管理事实间的支持、矛盾、更新关系，支持置信度传播计算（支持事实提升置信，矛盾事实降低置信）。AI驱动的关系发现能自动连接孤立知识点，形成网状知识结构。SurrealDB的SurrealQL提供强大的图遍历能力，结合1536维向量索引，实现语义相似性与结构化关系的混合查询。内置的维护机制（decay/prune/consolidate）确保记忆库长期健康，避免信息过载。

潜在缺点
系统强依赖OpenAI API（嵌入与提取），无法完全离线运行，且会产生API费用。SurrealDB的安装配置对非技术用户存在门槛，特别是curl|sh安装方式在企业环境可能受限。作为T3来源的社区项目，虽代码规范但缺乏企业级支持背书。置信度算法参数（如0.05月衰减率）为硬编码，缺乏动态调整接口，可能需要修改源码适配特殊场景。

适合群体
适合需要长期记忆能力的AI助手开发者、构建个人知识库的研究人员，以及需要事实关联追踪的内容管理场景。对需要严格数据主权控制（必须离线）或无法使用OpenAI服务的用户不适用；也不适合对第三方脚本执行有严格限制的企业生产环境。

使用风险
主要风险包括：install.sh执行远程脚本可能存在供应链攻击面；integrate-clawdbot.sh使用sed修改源代码可能导致系统不稳定；默认root/root凭据若未修改存在未授权访问风险；OPENAI_API_KEY需妥善管理避免泄露。建议生产环境手动安装SurrealDB、修改凭据、使用scoped API key，并在运行集成脚本前备份源码。

核心用法

SurrealDB Knowledge Graph Memory 是一个为AI助手设计的长期记忆系统，通过知识图谱结构存储、关联和检索事实信息。

主要功能模块

1. MCP工具集（4个核心工具）

• knowledge_search: 语义搜索事实，返回相似度×置信度加权结果
• knowledge_recall: 召回事实及其完整上下文（关联实体、支持/矛盾关系）
• knowledge_store: 存储新事实，支持置信度评分和标签分类
• knowledge_stats: 获取知识图谱统计信息

2. LLM知识提取
从 MEMORY.md 和 memory/*.md 文件中自动提取结构化事实，使用GPT-4o-mini识别实体和关系，支持增量提取和文件变更追踪。

3. 智能关系管理
自动发现事实间的语义关联，创建 supports/contradicts/updates/elaborates 四种关系边，可手动或通过定时任务触发。

4. 置信度评分系统
有效置信度 = 基础置信度 + 支持事实继承加成 + 成熟实体加成 - 矛盾事实损耗 - 时间衰减（每月5%）

5. 记忆维护机制

• 衰减（decay）：对陈旧事实降低置信度
• 剪枝（prune）：删除低置信度过时事实
• 合并（consolidate）：融合近似重复事实

快速启动流程

# 1. 手动安装SurrealDB（推荐跳过curl|sh）
# 2. 创建Python虚拟环境并安装依赖
python3 -m venv .venv && source .venv/bin/activate
pip install -r scripts/requirements.txt
# 3. 设置API密钥
export OPENAI_API_KEY="sk-..."
# 4. 初始化数据库
./scripts/init-db.sh
# 5. 运行知识提取
python3 scripts/extract-knowledge.py extract --full

网关集成

提供Clawdbot控制面板集成，支持通过RPC调用管理记忆系统：健康检查、统计查看、自动修复、提取进度监控、维护操作等。

---

显著优点

架构设计先进

• SurrealDB原生支持图数据模型，关系查询效率高
• 向量索引实现语义搜索，超越传统关键词匹配
• 置信度传播机制模拟人类记忆的可信度评估

LLM深度集成

• 自动从自然语言文档提取结构化知识
• AI驱动的关系发现减少人工标注成本
• OpenAI嵌入模型（text-embedding-3-small）确保语义质量

维护自动化

• 时间衰减模拟记忆遗忘曲线
• 矛盾检测自动标记冲突信息
• 定时维护任务保持图谱健康

生态兼容

• MCP协议支持，可与任意MCP客户端集成
• Clawdbot网关原生集成，提供Web管理界面
• 多CLI工具满足不同使用场景（简单查询/完整CRUD/批量提取）

---

潜在缺点与局限性

部署复杂度较高
需要同时维护：SurrealDB服务、Python虚拟环境、OpenAI API密钥、YAML配置文件。对非技术用户门槛较高。

外部依赖强

• 强制依赖OpenAI API（嵌入+提取），无法离线运行
• 无OpenAI替代方案，成本受制于OpenAI定价
• SurrealDB作为外部服务增加运维负担

安全风险点

• install.sh 使用 curl|sh 动态下载（官方来源但仍有供应链风险）
• integrate-clawdbot.sh 自动修改外部源代码
• 默认凭证 root/root 需用户主动修改

性能与成本权衡

• 每次存储需调用OpenAI API生成嵌入（成本累积）
• 大规模图谱的关系发现计算开销大
• 向量索引需足够内存支持

功能局限

• 仅支持Markdown格式的记忆文件
• 关系类型固定四种，扩展需改源码
• 无内置多用户/权限隔离机制

---

适合人群

强烈推荐

• 开发AI Agent需要长期记忆的技术团队
• 已使用Clawdbot生态的用户（网关集成完善）
• 需要知识溯源和置信度评估的研究场景
• 愿意投入运维成本换取记忆质量的专业用户

谨慎考虑

• 个人轻度用户（维护成本过高）
• 完全离线环境需求（强制OpenAI依赖）
• 预算敏感场景（API调用持续产生费用）
• 无技术背景用户（部署流程复杂）

---

常规风险

| 风险类别 | 具体表现 | 缓解措施 |

|---------|---------|---------|

| **供应链攻击** | `curl|sh` 安装脚本被篡改 | 手动下载官方发布包，校验SHA256 |

| **代码注入** | `sed` patching 修改Clawdbot源码 | 审查`integrate-clawdbot.sh`，使用`--dry-run`预览 |

| **凭证泄露** | 默认`root/root`被扫描利用 | 首次运行强制修改，绑定localhost |

| **API密钥暴露** | `OPENAI_API_KEY` 环境变量泄露 | 使用最小权限scoped key，定期轮换 |

| **数据隐私** | MEMORY.md内容上传OpenAI | 本地评估敏感程度，考虑数据脱敏 |

| **服务可用性** | OpenAI/SurrealDB服务中断 | 设计降级策略，本地缓存关键嵌入 |

安全认证结论

安全等级B（65分），来源可信度T2（openclaw组织）。基础安全级别，功能与声明一致，动态代码下载和源文件patching风险可控但需用户审查后使用。建议：生产环境修改默认凭证、跳过自动安装脚本手动部署、审查patching修改内容后再执行。