graph-memory 是什么？把 DeepSeek Harness 对话变成知识图谱记忆

graph-memory 是 DeepSeek Harness（DSH Plugin）生态中的原生知识图谱记忆插件，把对话历史改写成可追溯、可搜索、跨会话复用的知识图谱：它把经验沉淀为 TASK、SKILL、EVENT 三类节点和类型化边，召回时只注入相关的局部子图而不是重放完整历史，从而压缩上下文、减少 token 消耗。 本文基于官方 README 介绍它是什么、核心功能、安装启用、典型用法与常见排错。

graph-memory 是什么？

graph-memory 解决「AI 代理上下文膨胀、经验随会话丢失」的问题：把对话历史变成结构化知识图谱，让「过去哪些知识现在值得召回」代替「把整段历史塞回提示词」。 以下定位与事实均来自官方 README（来源）：

graph-memory 由 adoresever 用 TypeScript 开发、以 MIT 协议开源。README 用一句话区分它和上下文压缩：「Compaction 回答『这段对话还剩多少能放下』，Graph Memory 回答『现在值得召回哪些过去的知识』」。可复用的对话知识变成类型化节点——TASK（目标、执行与结果）、SKILL（验证过的可复用方法）、EVENT（错误、修复、决策、变更与事实），再用 USED_SKILL、SOLVED_BY、REQUIRES、PATCHES、CONFLICTS_WITH 等类型化边保留关系。新问题到来时，插件检索一个相关的局部子图，而不是重放完整历史。它是 DSH 的原生插件（Cordis 适配器），默认用 SQLite 存储、无需图数据库，需要 Node.js 22.13+。

graph-memory 的核心功能有哪些？

graph-memory 的核心能力是「原生宿主集成、持久跨会话记忆、上下文压缩、智能召回与本地优先」：让 AI 代理把每次对话沉淀为可复用知识，并在后续会话中按需、可追溯地召回。 这些能力全部来自官方 README（来源）：

• 原生宿主集成：经 DSH / Cordis 插件生命周期加载，而不是通过 MCP 侧信道模拟；接入 Session、Tool、Agent Loop、Prompt Assembly、LLM 与 Credentials 等接口，不 fork、不修改 DSH 核心。
• 持久跨会话记忆：会话 A 的知识可在会话 B 自动召回；记忆在 DSH 重启后依然存在；稳定事件 ID 让恢复与热重载摄入保持幂等；来源会话和图边会解释「为什么召回这条记忆」。
• 上下文压缩：保留最新真实用户轮次（freshTurnCount，默认 5），旧前缀经 DSH 压缩服务替换为滚动检查点，进入当前提示词的只有相关子图，受 recallTokenBudget（默认 4096）约束；在特定七轮工作流中实测减少约 75% token（场景级对比，非普遍保证）。
• 智能召回：语义向量检索 + FTS5 词法回退，社区检测、PageRank 与有界图遍历；自动注入经高精度语义门控（autoRecallMinScore，默认 0.6），且不会回退到与查询无关的社区代表。
• 本地优先与轻量：默认 SQLite、无需图数据库；嵌入可选，未配置时回退 FTS5；数据默认留在本地 profile；支持 DashScope、OpenAI 与本地提供方的 OpenAI 兼容嵌入。
• 可观测可验证：gm_status 报告存储路径、图计数、向量覆盖等状态；模型或维度变化触发重新嵌入；关键知识可用 gm_record 确定性记录。

怎么安装与启用 graph-memory？

安装 graph-memory 只需要一条命令：当前 beta（1.6.0-beta.9）尚未发布到 npm，但仓库自带预构建运行时，可通过 GitHub 源无脚本安装。 安装命令与验证步骤来自官方 README（来源），前置条件是 Node.js 22.13+：

1. 安装 graph-memory：在 DeepSeek Harness 终端执行安装命令，把插件装进当前 profile：

npx @deepseek-ai/dsh plugin --profile web add github:adoresever/graph-memory

等待命令输出安装完成。也可以从检出目录构建 tarball 后安装：git clone → npm install → npm test → npm pack → 再 add /absolute/path/to/graph-memory-1.6.0-beta.9.tgz。

2. 更新 graph-memory：重跑安装命令即可覆盖为最新版本：

npx @deepseek-ai/dsh plugin --profile web update github:adoresever/graph-memory

3. 卸载 graph-memory：不再需要时执行卸载命令：

npx @deepseek-ai/dsh plugin remove graph-memory

4. 启用并验证：安装后确认插件已启用，并查看当前配置：

npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

安装完成后，在「设置 → 插件 → 插件列表」确认 graph-memory/dsh 已启用。默认存储位置为 $DSH_HOME/graph-memory/graph-memory.db；未设置 DSH_HOME 时通常为 ~/.dsh/graph-memory/graph-memory.db。

graph-memory 典型用法

graph-memory 的日常使用几乎无需干预——插件在 Prompt Assembly 阶段自动召回相关记忆；需要确定性记录或主动检索时，用 gm_record 与 gm_search 两个命令。 以下命令来自官方 README（来源）：

1. 记录关键知识：自动提取依赖辅助模型输出稳定性，beta 阶段的重要知识用 gm_record 确定性落库：

npx @deepseek-ai/dsh gm_record

2. 主动检索长期记忆：gm_search 做显式、广泛的图谱搜索（自动召回更精准，显式搜索覆盖面更广）：

npx @deepseek-ai/dsh gm_search

3. 查看插件状态：gm_status 报告存储路径、图计数、向量覆盖、模式与维度：

npx @deepseek-ai/dsh gm_status

注意：自动召回不需要显式调用 gm_search——Prompt Assembly 期间插件会自动注入相关记忆；工具列表里还有 gm_stats（节点、边、类型与社区统计）。

4. 可选：配置向量嵌入：想让召回走语义向量而非 FTS5 词法检索，配置 DashScope 等 OpenAI 兼容端点后启动：

export GRAPH_MEMORY_EMBEDDING_API_KEY='replace-with-your-key'
export GRAPH_MEMORY_EMBEDDING_BASE_URL='https://dashscope.aliyuncs.com/compatible-mode/v1'
export GRAPH_MEMORY_EMBEDDING_MODEL='text-embedding-v4'
export GRAPH_MEMORY_EMBEDDING_DIMENSIONS='1024'
dsh web

不要在聊天里发送密钥——Cordis 只存凭据引用，DSH credentials 在每次嵌入操作时解析真实值；没有嵌入时插件继续用 FTS5，不阻塞对话。

graph-memory 常见问题与排错

graph-memory 的常见问题集中在「装了不生效」「召回不到旧知识」「嵌入配置失败」三类，下面给出症状、原因与解决步骤。 排错依据来自官方 README（来源）：

1. 症状：装完对话里没有自动召回旧知识。 原因：插件未启用，或自动召回需要先在同一存储里积累知识。解决：确认「设置 → 插件 → 插件列表」里 graph-memory/dsh 处于启用状态；会话 A 的知识要先被提取进图才能被会话 B 召回；用 gm_status 查看存储路径与图计数：

npx @deepseek-ai/dsh gm_status

2. 症状：关键知识没被记住、提取不稳定。 原因：自动提取依赖辅助模型输出稳定性。解决：用 gm_record 确定性记录关键知识：

npx @deepseek-ai/dsh gm_record

3. 症状：想用语义向量召回但命中很差。 原因：未配置嵌入，召回回退到 FTS5 词法检索；或模型 / 维度变化后尚未重新嵌入。解决：按 README 配置 DashScope 等嵌入环境变量后重启（见「典型用法」），再用 gm_status 查看向量覆盖；模型或维度变化会自动触发重新嵌入。

4. 症状：gm_update / gm_maintain 报不存在。 原因：这两个工具目前是 OpenClaw 入口工具，DSH 尚未暴露。解决：在 DSH 下用 gm_record 记录、gm_search 检索即可，无需这两个命令。

适用场景与注意

graph-memory 适合「需要跨会话复用经验、上下文越来越长」的 DSH 工作流；它默认本地存储，但也因此有一些限制需要知道。 事实来自官方 README（来源）：

适用场景：长会话与多会话项目，让经验跨会话复用；token 敏感的工作流，场景级实测约 75% 上下文压缩；需要可追溯来源的记忆，召回时解释「为什么召回这条」。

注意与限制：

• 当前 beta 未发布到 npm，安装走 GitHub 源或源码 tarball；
• 自动提取依赖辅助模型输出稳定性，关键知识请用 gm_record；
• 数据默认留在本地 SQLite，API 密钥来自宿主凭据或环境变量、不写入数据库；任何出现在聊天、日志或截图中的密钥都应轮换；
• 召回历史被标记为不可信参考材料，不会覆盖当前用户指令；
• 不同维度的向量从不静默比较，模型或维度变化会触发重新嵌入。

项目链接

graph-memory 是 adoresever 维护的 MIT 开源项目，DSH 侧当前为 beta 版本（1.6.0-beta.9）。

前往插件详情页查看完整信息：graph-memory。

本页是基于该插件官方 README 独立重写的导读——权威文档和最新变更请以源头为准：adoresever/graph-memory。插件是安装时就在你机器上运行的第三方代码；收录不代表背书——安装前请自行审阅源码。