# graph-memory

> Provides a local SQLite knowledge

## Metadata

- Author: [@adoresever](https://github.com/adoresever)
- Repo: <https://github.com/adoresever/graph-memory.git>
- GitHub: [adoresever/graph-memory](https://github.com/adoresever/graph-memory)
- Stars: 562
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `claude-code`, `codex`, `deepseek`, `deepseek-harness`, `dsh`, `dsh-plugin`, `dsh-plugins`, `knowledge-graph`, `memory`, `openclaw`, `openclaw-plugin`, `opencode`
- Forks: 80
- Open Issues: 9
- Last push: 2026-08-20T13:19:27.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:adoresever/graph-memory
```

## Wiki

## One-Sentence Positioning
graph-memory沉淀AI对话中产生的任务、技能、事件及其关系成本地知识图谱，并在新问题出现时只召回相关的局部子图注入上下文，从而让DeepSeek Harness拥有可追溯、可搜索、跨会话共享的长期记忆。

## Core Capabilities
- 自动把对话消息抽取成TASK / SKILL / EVENT三类节点，带USED_SKILL、SOLVED_BY、REQUIRES、PATCHES、CONFLICTS_WITH几类因果关系
- 每个节点都关联原始user / assistant片段，召回时能告诉用户这条记忆来自哪个会话、因为什么被想起
- 在Prompt Assembly阶段自动检索相关子图注入system prompt，不需要模型主动调用工具
- 提供gm_status、gm_search、gm_record、gm_stats四个原生工具，支持主动搜索、确定性记录和统计查看
- 支持语义向量检索（可选）与SQLite FTS5全文检索双通道：未配向量时自动降级到FTS5，永远不阻断对话
- 跨DSH重启保留数据，事件ID稳定使HMR和恢复期间不会重复入库

## Technical Implementation
- **Language**: TypeScript
- **Key Dependencies**: `@photostructure/sqlite`（本地SQLite存储 + FTS5）、`@sinclair/typebox`（Schema）、可选的OpenAI兼容Embedding HTTP服务
- **Architecture Pattern**: 宿主无关内核 + 双宿主适配器 —— `dsh.ts`作为DeepSeek Harness / Cordis适配器走bundle.patch自动注入；`index.ts`保留对OpenClaw的兼容入口；`src/{extractor,recaller,graph,store,format,engine}`六个子目录共享一套算法层
- **Entry Files**: `dsh.ts`（DSH入口，apply函数挂载tools / llm / systemPrompt / agentLoop / sessions / credentials六个接缝），`cordis.patch.yml`（DSH bundle声明）

## Use Cases
日常用DSH跟AI协作开发时，经常出现几周前讨论过某个库的用法、某次bug修复方案、某个API设计决策，但新会话里模型完全不知道 —— 用户不得不反复贴历史。Graph Memory让模型在每次新会话启动前自动看到这些沉淀下来的知识，无需手动复制粘贴。它也适合长流程项目（持续数天的开发任务、多分支并行迭代），因为它能区分不同来源节点并保持召回路径可解释。

## Prerequisites and Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.5实测验证（DSH仍为Developer Preview） | 插件走Cordis bundle.patch注入；当前DSH未公开最低版本约束 |
| Node.js | >=20（package.json声明）；DSH实际使用建议22.19+或24+ | |
| Platform | macOS / Windows / Linux | 跨平台，无额外系统库要求 |
| Native Module | `@photostructure/sqlite`（native） | `@photostructure/sqlite`跨平台预编译；`@sinclair/typebox`纯JS |

## Installation
```bash
dsh plugin --profile web add github:adoresever/graph-memory
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `dbPath` | string | SQLite图谱数据库存放路径，留空则使用`$DSH_HOME/graph-memory/graph-memory.db` | `~/.dsh/graph-memory/graph-memory.db` |
| `extractionEnabled` | boolean | 是否启用自动从对话里抽取任务/技能/事件 | `true` |
| `recallEnabled` | boolean | 是否在Prompt Assembly阶段自动注入相关记忆 | `true` |
| `recallMaxNodes` | integer | 跨会话召回时最多向当前prompt注入的节点数 | `6` |
| `recallMaxDepth` | integer | 图遍历深度（从召回种子节点出发走几跳） | `2` |
| `maintenanceInterval` | integer | 每隔多少轮检查一次信号，触发PageRank + 社区检测 | `6` |
| `embedding.apiKeyEnv` | string | Embedding服务的key在启动环境里的变量名（如`GRAPH_MEMORY_EMBEDDING_API_KEY`），由DSH Credentials解析真实值 | 未设置 |
| `embedding.baseURL` | string | Embedding服务的接口地址，OpenAI兼容，DashScope / OpenAI / 本地服务都能接 | OpenAI默认 |
| `embedding.model` | string | 向量模型名，默认`text-embedding-3-small` | `text-embedding-3-small` |
| `embedding.dimensions` | integer | 向量维度（如DashScope text-embedding-v4为1024），仅在服务支持时设置 | 由服务决定 |

> 未列出的env变量名对照：`GRAPH_MEMORY_EMBEDDING_API_KEY` / `GRAPH_MEMORY_EMBEDDING_BASE_URL` / `GRAPH_MEMORY_EMBEDDING_MODEL` / `GRAPH_MEMORY_EMBEDDING_DIMENSIONS`，由`cordis.patch.yml`读取并注入到上面这套字段里。

## FAQ

**Q: 这个插件需要联网吗？API key会泄露吗？**

A: 默认完全离线运行，只有当用户主动配置向量服务（Embedding）时才会发请求。key只以环境变量名形式写在Cordis patch里，真实密钥由DSH Credentials解析，数据库里不会持久化任何secret。

**Q: 卸载插件会丢失我之前的记忆吗？**

A: 不会丢失。SQLite数据库独立于插件存在，禁用或卸载插件都只是不再读取/写入，原`graph-memory.db`随时可重新挂载复用。

**Q: 想清空记忆怎么操作？**

A: 关闭插件后手动删除`$DSH_HOME/graph-memory/graph-memory.db`文件即可。Community版未提供一键清空工具，删除前建议备份。

**Q: 跟DSH自带的会话压缩有冲突吗？**

A: 不冲突。压缩决定当前窗口还能装多少原始历史，图谱记忆决定哪些"已经被消化过的知识"值得在下一轮唤醒 —— 两者目标正交，可同时启用。

**Q: 自动抽取偶尔漏掉重要内容怎么办？**

A: 用`gm_record`工具主动写入，给出name / type（TASK/SKILL/EVENT）/ description / content四个字段，会跳过LLM抽取链路直接落库，可作为beta阶段的兜底手段。

**Q: DSH模式下找不到gm_update / gm_maintain？**

A: 这是预期行为。DSH/Cordis适配器只暴露gm_status、gm_search、gm_record、gm_stats四个工具，gm_update和gm_maintain暂时保留在OpenClaw入口，DSH端未实现。

**Q: 是否支持中文和长内容？**

A: FTS5检索对中文按unicode分词匹配；向量检索走Embedding模型，与语种无关。长内容会被分块抽取，不要求完整塞进单条节点。

## Difficulty Level
进阶 — 需要懂DSH的Cordis bundle安装机制、能配置Embedding服务的环境变量，并理解SQLite与FTS5的基本概念才能调优召回；但装好即用的默认配置也能正常工作，普通用户也能跑起来。

## Known Issues and Limitations
- DSH版暂未暴露`gm_update`和`gm_maintain`工具，这两个能力目前只在OpenClaw入口可见
- 自动抽取依赖辅助模型输出的稳定性，关键知识建议使用`gm_record`工具手动写库
- 当前beta 1.6.0-beta.1还未发布到npm registry，必须通过`git clone` + `npm run build` + `npm pack`走本地tarball安装
- DSH端Pro版（Neo4j适配器 + 可视化工作台 + Client Plugin）尚未实现，Community版只走SQLite
- 配置项`freshTailCount`在`openclaw.plugin.json`中已被标记deprecated（旧方案按"新鲜尾部"切分，现已改为按用户轮次切分，不再生效）
- DSH仍处于Developer Preview阶段，后续版本可能引入破坏性变更，插件在`0.1.0-rc.5`上验证过

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [graph-memory](https://deepseek-plugin.org/plugins/adoresever/graph-memory)
Wiki generated by AI (model: `MiniMax-M2.5`)