graph-memory：从对话中生长出来的知识图谱

当 AI 开始"长记性"

想象这样一个场景：你让 Claude Code 帮你部署一个 Docker 服务，折腾了半小时终于成功。第二天，你换了个新任务——部署一个 Node.js 应用。Claude Code 翻车了，花了同样的时间重蹈覆辙。你忍不住想："你不是应该有记忆吗？"

这就是当前 AI 编程工具的致命软肋：上下文窗口是有成本的，记忆是无结构的。当对话轮次达到第 7 轮时，无记忆的 Claude Code 上下文膨胀到 95K token，其中 95% 是噪音——pip 日志、git diff、报错堆栈，真正的"我成功解决了什么问题、用了什么技能"淹没在垃圾山里。

graph-memory 就是来解决这个问题的。它是 OpenClaw 的记忆插件，用知识图谱取代传统的 markdown 记忆文件，让 AI 在跨对话场景下也能精准召回曾经踩过的坑、解过的 bug、用过的技能。

图1：graph-memory 在 OpenClaw 中的工作位置——接管上下文引擎，监听每轮对话，自动提取三元组入图谱。

项目背景与核心定位

graph-memory 由独立开发者 adoresever 开发，采用 MIT 许可证，当前版本 1.5.8。这是一个专为 OpenClaw（AI 编程工具框架）设计的上下文引擎插件，核心功能是：从对话中自动提取结构化知识，构建类型化属性图，并通过个性化 PageRank 实现精准召回。

从技术路线看，graph-memory 走的是图数据库 + 信息检索融合路线，而非 RAG（检索增强生成）常见的大模型向量库路线。它的核心假设是：AI 对话中蕴含的"经验"天然具有图结构——技能与技能之间有依赖关系，任务与解决方案之间有因果关系，这种结构化信息用图来表达远比用向量来表示更精确、更可解释。

项目在 GitHub 获得 500+ star，相关话题涵盖 agent、claude-code、codex、knowledge-graph、memory、openclaw、opencode 等，反映出它对多个 AI 编程生态的通用价值。

图2：7轮对话实测——无 graph-memory 时上下文线性膨胀至 95K token；有 graph-memory 时压缩至 24K，降幅达 75%。

架构设计：三库合一

graph-memory 的技术栈可以拆解为三个核心子系统：存储层、提取层、召回层。

存储层：SQLite 图数据库

存储层基于 SQLite（通过 @photostructure/sqlite，一个预编译二进制库，无需 node-gyp 编译），数据库文件默认路径 ~/.openclaw/graph-memory.db。这是一个巧妙的工程选择：SQLite 是嵌入式场景的最优解之一，启动快、零配置、无守护进程，且通过 SQLite 的 CTE（公用表表达式）可以优雅地实现图遍历查询。

数据库包含 7 张核心表：

• gm_nodes：知识节点，含 type（TASK/SKILL/EVENT）、name、description、content、pagerank 分数、community_id
• gm_edges：类型化关系边，含 USED_SKILL / SOLVED_BY / REQUIRES / PATCHES / CONFLICTS_WITH 五种关系类型
• gm_nodes_fts：FTS5 全文索引，当未配置 embedding 时作为降级搜索方案
• gm_vectors：Embedding 向量表（可选，配置 embedding 后启用）
• gm_communities：社区摘要表，含 LLM 生成的社区描述和 embedding
• gm_messages：原始对话消息持久化
• gm_signals：信号检测结果

关键设计细节：消息入库时 turn_index 从数据库最大值续接，重启后不归零。这解决了大多数记忆系统"重启即失忆"的顽疾。

提取层：LLM 三元组提取

知识提取在 afterTurn 阶段（后台异步，不阻塞用户对话）触发。每隔固定轮次（默认 7 轮），graph-memory 调用 LLM 从对话历史中提取结构化三元组：

用户："帮我安装 bilibili-mcp"
助手："执行 pnpm install -g @anthropic/bilibili-mcp"
[提取] → TASK("安装bilibili-mcp") — SOLVED_BY — SKILL("pnpm全局安装")

提取过程零依赖 OpenClaw 内部 API，仅解析对话文本——这意味着它具有跨平台潜力，理论上可以适配任何会话式 AI 系统。LLM 配置支持任何 OpenAI 兼容端点，包括本地 Ollama 模型，这对隐私敏感场景很有意义。

在 session_end 阶段，还有一个 finalize 逻辑：EVENT 节点（如 "ImportError: libGL.so.1"）经过 LLM 判断可以升级为 SKILL 节点（"解决方案：安装 libgl1"），实现从"问题记录"到"技能沉淀"的跃迁。

召回层：双路径 + 个性化 PageRank

这是 graph-memory 最有技术含量的部分，也是与其他记忆方案拉开差距的核心。

召回有两条并行路径：

精确路径（实体级）：向量/FTS5 搜索 → 找到种子节点 → 社区同伴扩展 → 图遍历（N 跳）→ 个性化 PageRank 排序

泛化路径（社区级）：查询向量 vs 社区摘要 embedding → 匹配社区 → 取出社区成员节点 → 个性化 PageRank 排序

两条路径并行执行，结果合并去重后注入上下文。泛化路径是 v2.0 新增的，它的价值在于：当用户问"conda 环境问题"但图谱中恰好没有 conda 相关节点时，泛化路径可以通过社区摘要的 embedding 命中"Python 环境管理"社区，从而召回相关技能。

**个性化 PageRank（PPR）**是排序算法。传统 PageRank 是全局固定的——一个节点在整个图中的重要性是恒定的。但 PPR 根据当前查询动态调整：从查询节点出发，随机游走倾向于访问与查询相关的区域，最终按"与当前问题的相关性"排序。

图3：58 个节点、40 条边、3 个社区——从对话中自动提取的知识图谱。右侧面板展示社区聚类，左侧展示 Agent 查询图谱的 gm_search 工具输出。

部署体验：安装简单，配置有门槛

从安装角度，graph-memory 提供了三种方式：

• Windows exe 安装包（v2.0 新增）：下载运行，自动检测 OpenClaw 路径，一键完成安装和配置
• pnpm openclaw plugins install：一条命令搞定插件安装
• 源码编译：适合开发或自定义修改

但安装之后，激活上下文引擎这一步容易遗漏。必须手动在 ~/.openclaw/openclaw.json 中添加 "plugins.slots.contextEngine": "graph-memory"，否则插件虽然注册了，但 ingest/assemble/compact 管线不会启动——数据库里永远是空的。这是文档中明确强调的"最容易遗漏的一步"，实际使用中仍会有人踩坑。

配置方面需要提供 LLM API Key（必填）和 Embedding API Key（可选，推荐）。LLM 支持所有 OpenAI 兼容端点，Embedding 同样原生支持 Ollama 本地模型，这在隐私敏感场景下是一个差异化优势。

部署后验证也很简单：直接查 SQLite 数据库——SELECT COUNT(*) FROM gm_messages 看消息是否入库，SELECT type, name FROM gm_nodes LIMIT 10 看三元组是否提取成功。

技术亮点与局限

亮点

零依赖 embedding SDK：Embedding 模块改用原生 fetch 实现，直接调用 POST /embeddings 接口，天然兼容所有 OpenAI 兼容端点。这消除了传统方案对 openai npm 包的依赖，也避免了 SDK 版本兼容问题。

75% Token 压缩：实测 7 轮对话，从 95K 压缩到 24K。背后的逻辑是：图谱注入的是结构化三元组（SKILL、REQUIRES、SOLVED_BY），而不是原文复述，压缩率高是必然的。

溯源片段（Episodic Context）：v2.0 新增的特性，PPR 排名前 3 的节点会拉取原始 user/assistant 对话片段注入上下文。Agent 不仅看到结构化的"解决方案"，还能看到产生这个知识的原始对话，提高了复用准确性。

向量去重：通过余弦相似度（默认阈值 0.90）合并语义重复的节点，避免图谱膨胀。

局限

强依赖 OpenClaw：作为 OpenClaw 的插件，graph-memory 无法独立使用。如果你的工作流不是围绕 OpenClaw 构建，这个项目基本无用武之地。

SQLite 的扩展性上限：SQLite 是嵌入式数据库，不是为大规模图数据设计的。当节点数达到数万甚至更多时，SQLite CTE 遍历和 PPR 计算的性能会显著下降。

配置复杂度：安装简单，但配置 LLM + Embedding API Key、激活 contextEngine、验证安装——这套流程对非技术用户来说仍有门槛。Windows exe 安装包在一定程度上缓解了这个问题。

行业意义

graph-memory 代表了一个值得关注的方向：从"记忆是向量相似度"到"记忆是图结构"的技术范式转换。在 AI Agent 领域，上下文管理是一个核心挑战——如何在有限的上下文窗口中最大化有效信息密度。RAG 方案（向量检索）解决了大规模知识库场景的问题，但 graph-memory 解决的是另一个问题：个人化、动态、跨会话的经验积累。

从更宏观的视角看，graph-memory 反映了 AI 编程工具的一个发展趋势：从"每次对话都是全新开始"向"跨会话持续学习"的演进。Claude Code、MCP、OpenClaw 这些工具都在朝这个方向努力，graph-memory 是这个生态中一个非常有特色的节点级记忆方案。

作者 adoresever 在项目文档中明确提到了与 lossless-claw（另一个上下文压缩方案）的对比：lossless-claw 用摘要 DAG，graph-memory 用知识图谱；前者是无损文本压缩，后者是无损语义结构化——两者解决的是同一类问题，但技术路线完全不同，各有适用场景。