graph-memory

一句话定位

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

核心能力

• 把对话消息自动抽成 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 和恢复期间不会重复入库

技术实现

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

适用场景

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

前置依赖与兼容性

安装方式

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

配置项

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

常见问题

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 模型，与语种无关。长内容会被分块抽取，不要求完整塞进单条节点。

上手难度

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

已知问题与限制

• 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 上验证过

Traceable, searchable, cross-session memory for AI agents.
One memory core, native to DeepSeek Harness, with the OpenClaw plugin entry retained.

中文 · Advantages · Architecture · DSH Install · Pro Plugin · Technical Report (Chinese)

Compaction answers “how much of this conversation still fits?” Graph Memory answers “which past knowledge is worth recalling now?”

Reusable conversation knowledge becomes typed nodes:

• TASK: goals, execution, and outcomes;
• SKILL: validated reusable methods;
• EVENT: errors, fixes, decisions, changes, and facts.

Typed edges such as USED_SKILL, SOLVED_BY, REQUIRES, PATCHES, and CONFLICTS_WITH preserve relationships. A new question retrieves a relevant local subgraph instead of replaying the complete history.

Core advantages

Native host integration

• Loaded by the DSH/Cordis plugin lifecycle, not simulated through an MCP side channel.
• Integrates Session, Tool, Agent Loop, Prompt Assembly, LLM, and Credentials seams.
• Disposes database, cache, and event listeners with its plugin fiber.
• Does not fork or modify DeepSeek Harness core.

Durable cross-session memory

• Knowledge from Session A can be recalled automatically in Session B.
• Memory survives DSH restarts.
• Stable event IDs make resume and HMR ingestion idempotent.
• Source sessions and graph edges explain why a memory was recalled.

Smaller, cleaner context

• Semantic vector retrieval with FTS5 lexical fallback.
• Community detection, PageRank, personalized PageRank, and bounded graph traversal.
• Only a relevant local subgraph enters the current prompt.
• Recalled history is marked as untrusted reference material and cannot override current user instructions.

Local-first and lightweight

• Community uses SQLite by default; no graph database deployment is required.
• Embeddings are optional. Without them, recall falls back to FTS5.
• Data remains in the user's local profile by default.
• OpenAI-compatible embeddings support DashScope, OpenAI, and local providers.

Observable and verifiable

• gm_status reports store path, graph counts, vector coverage, mode, and dimensions.
• Model or dimension changes trigger re-embedding.
• Vectors with different dimensions are never silently compared.
• Critical knowledge can be recorded deterministically with gm_record.

Scoped token benchmark

The original OpenClaw adapter was measured in a seven-turn workflow that installed, authenticated, and queried bilibili-mcp:

The measured reduction at R7 was approximately 75% in that specific workflow. This is a scenario-level comparison, not a universal savings guarantee; the mechanism is replacing indiscriminate history replay with a relevant knowledge subgraph.

Project evolution

The DSH integration does not discard the original project. Graph Memory is evolving from an OpenClaw memory plugin into a graph-memory core that different agent harnesses can load natively.

On March 15, 2026, the project owner presented Graph Memory's architecture at the CLAW program event held in Tsinghua Science Park. The following owner-supplied materials and the Sina Finance event report document that development.

• Community cross-session memory demo
• Graph Memory Pro technical presentation

The image below is the existing OpenClaw / ClawX-era Pro graph prototype. It demonstrates a previously explored interaction direction; it is not a shipped DSH frontend.

Names and venue information document project history only and do not imply endorsement by Tsinghua University, Sina Finance, DeepSeek, or OpenClaw.

Graph Memory architecture

Typed knowledge graph

TASK   ──USED_SKILL──▶ SKILL
TASK   ──SOLVED_BY───▶ EVENT
SKILL  ──REQUIRES────▶ SKILL
EVENT  ──PATCHES─────▶ SKILL
SKILL  ──CONFLICTS_WITH──▶ SKILL

Nodes retain episodic user/assistant provenance. This preserves the context in which knowledge was created, not only a lossy summary.

Dual-path recall

flowchart LR
  Q[Current query] --> EXACT[Exact path]
  Q --> GENERAL[Generalized path]
  EXACT --> SEARCH[Vector / FTS5]
  SEARCH --> EXPAND[Community expansion + traversal]
  GENERAL --> SUMMARY[Community-summary match]
  SUMMARY --> MEMBERS[Community members]
  EXPAND --> PPR[Personalized PageRank]
  MEMBERS --> PPR
  PPR --> CONTEXT[Deduplicated local context]

Host data flow

flowchart LR
  USER[User message] --> SESSION[DSH Session Events]
  SESSION --> ADAPTER[Graph Memory Cordis Adapter]
  ADAPTER --> EXTRACT[Structured Extraction]
  EXTRACT --> GRAPH[(SQLite / FTS5 / Vectors)]

  USER --> RECALL[Semantic + Lexical Recall]
  GRAPH --> RECALL
  RECALL --> RANK[Community Expansion + PPR]
  RANK --> PROMPT[Prompt Assembly]
  PROMPT --> LOOP[DSH Agent Loop]

  CREDS[DSH Credentials] --> ADAPTER
  TOOLS[gm_* Tools] --> ADAPTER

The code follows a host-neutral core plus host adapters:

graph-memory/
├── dsh.ts                 # DeepSeek Harness / Cordis adapter
├── index.ts               # OpenClaw adapter
├── cordis.patch.yml       # DSH bundle entry
└── src/
    ├── extractor/         # conversation → TASK / SKILL / EVENT
    ├── recaller/          # vector, FTS5, graph expansion and recall
    ├── graph/             # PageRank, communities and deduplication
    ├── store/             # SQLite schema and queries
    ├── format/            # safe context assembly
    └── engine/            # LLM and embedding providers

Native DeepSeek Harness status

Current beta: 1.6.0-beta.1. Local acceptance used DeepSeek Harness 0.1.0-rc.5. DSH remains in Developer Preview and may introduce compatibility-breaking changes. Testing covered tarball installation, active plugin state, 1024-dimensional vector backfill, semantic recall across Sessions, persistence across restarts, and FTS5 fallback. All 107 automated tests passed.

Plugin enabled: graph-memory/dsh is active in the DSH plugin list

Cross-session semantic recall in a fresh Session

Install on DeepSeek Harness

Prerequisites: Node.js 22.19+ or 24+. The current beta is not yet published to npm, so build the tarball from source:

git clone https://github.com/adoresever/graph-memory.git
cd graph-memory
npm ci
npm test
npm run build
npm pack

Install the generated tarball into the DSH Web profile:

npx @deepseek-ai/dsh plugin --profile web add /absolute/path/to/graph-memory-1.6.0-beta.1.tgz
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

# From a deepseek-harness source checkout:
pnpm dsh plugin --profile web add /absolute/path/to/graph-memory-1.6.0-beta.1.tgz
pnpm dsh web

After installation, verify that graph-memory/dsh is enabled under Settings → Plugins → Plugin list.

Default store:

$DSH_HOME/graph-memory/graph-memory.db

Without DSH_HOME, this is normally ~/.dsh/graph-memory/graph-memory.db.

Optional vector retrieval

Do not send secrets in chat. Cordis stores only a credential reference; DSH credentials resolves the real value for each embedding operation.

DashScope example:

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

Without embeddings, Graph Memory continues with FTS5 and does not block conversation.

DSH tools

Automatic recall does not require an explicit gm_search tool call. The plugin retrieves relevant memory during Prompt Assembly.

Graph Memory Pro as a DSH plugin

The accurate conclusion is not “Pro can already be installed into DSH.” It is: Pro's graph database, retrieval, PageRank, community, and CRUD backend can be migrated; its OpenClaw host code and old ClawX integration must be replaced by a DSH Host + Client Plugin. The current desktop-2.0 implementation is OpenClaw + Neo4j and contains no installable DSH Client renderer.

The reviewed desktop-2.0 code includes Neo4j Driver, GDS, APOC, vector indexes, graph maintenance tools, and CRUD routes. Today it also:

• imports openclaw/plugin-sdk at the entry;
• registers OpenClaw Gateway HTTP routes;
• writes OpenClaw configuration and restarts its Gateway during installation;
• exposes Neo4j connection details through /graph-memory-pro/neo4j-config;
• contains no installable DSH Client Plugin.

The correct plugin architecture is:

flowchart LR
  CORE[Graph Memory Core] --> STORE[SQLite default / Neo4j optional]
  STORE --> HOST[DSH Host Plugin]
  HOST --> REMOTE[Typed Remote API]
  REMOTE --> CLIENT[DSH Client Plugin]
  CLIENT --> SPLIT[Conversation + Graph split view]
  CLIENT --> DROP[Controlled drag-to-context]

The first Pro plugin does not need mandatory Neo4j:

• Pro Lite: SQLite plus a 2D/3D DSH graph client;
• Neo4j adapter: optional storage plugin for large graphs, GDS, and advanced analytics;
• the browser receives bounded GraphSnapshot data, never database passwords or arbitrary Cypher access;
• drag operations submit node IDs and intent; the Host validates them and writes visible, reversible Session context.

Pro should therefore be an optional Graph Memory DSH plugin module, not a separate standalone product.

Recommended package split

graph-memory                          # Community: current native Host Plugin
@adoresever/graph-memory-pro-dsh     # Pro: Host + Client Plugin, to be built
@adoresever/graph-memory-store-neo4j # Optional large-graph adapter, to be built

The first milestone should be Pro Lite: reuse the existing SQLite graph and add the DSH graph workbench, so users do not need Neo4j. Neo4j stays optional for larger graphs, GDS, and advanced analysis. This is a planned architecture; the existing desktop-2.0 Pro is still Neo4j-only and does not yet implement a switchable SQLite / Neo4j GraphStore.

Target installation experience

This illustrates the target experience only. The npm package [email protected] is still the OpenClaw release, and @adoresever/graph-memory-pro-dsh has not been published. These commands do not work today:

# PLANNED — NOT AVAILABLE YET
dsh plugin --profile web add graph-memory
dsh plugin --profile web add @adoresever/graph-memory-pro-dsh
dsh web

During development, install a local tarball:

npm run build
npm pack
dsh plugin --profile web add /absolute/path/to/graph-memory-pro-dsh-*.tgz

Four required integration layers

1. Core contracts: extract GraphStore, GraphSnapshot, and RecallResult so SQLite and Neo4j implement the same API.
2. Host Plugin: integrate DSH Sessions, Tools, LLM, System Prompt, and Credentials. Database secrets are resolved only on the Host.
3. Client Plugin: register a DSH sidebar, workbench, and tool card for 2D/3D graphs, search, filters, and split-view conversations.
4. Controlled context actions: drag-and-drop sends only a node ID and an intent; the Host validates it and writes visible, reversible Session Context.

The old Pro /graph-memory-pro/neo4j-config route returns connection details to the browser; this is a security flaw that must be removed. In the future DSH Pro design, the Host resolves Credentials and the browser receives only a bounded GraphSnapshot, never a Bolt password or unrestricted Cypher access.

OpenClaw compatibility

Existing OpenClaw users retain the original entry:

openclaw plugins install graph-memory
openclaw plugins enable graph-memory
openclaw gateway restart

The Context Engine slot must also be activated in ~/.openclaw/openclaw.json; otherwise the package may appear installed without running the full ingestion and extraction pipeline:

{
  "plugins": {
    "slots": {
      "contextEngine": "graph-memory"
    },
    "entries": {
      "graph-memory": {
        "enabled": true
      }
    }
  }
}

The Community memory core is host-neutral. DSH development does not require OpenClaw users to abandon their entry or data.

Development

npm ci
npm test
npm run build
npm pack

Release checks:

• tests and TypeScript build pass;
• tarball contains dist/dsh.js and cordis.patch.yml;
• no API keys, local databases, or environment files enter the repository;
• planned Pro features are never presented as shipped Community behavior.

Current limitations

• Automatic extraction depends on auxiliary-model output stability. Use gm_record for critical beta knowledge.
• DSH does not yet expose gm_update and gm_maintain; those remain OpenClaw-entry tools.
• The Pro DSH visualization client plugin is not implemented.
• npm registry publication is pending; install the current beta from a GitHub-built tarball.

Privacy and security

• Memory remains in local SQLite by default.
• API keys come from host credentials or environment variables, not the database or Cordis patch.
• Recalled history is reference material; current user instructions always take precedence.
• Rotate any secret that has appeared in chat, logs, or screenshots.

License

MIT © 2026 adoresever

See docs/ATTRIBUTIONS.md for asset, logo, and trademark notes.