graph-memory

Readme

# Graph Memory

<p align="center">
  <img src="docs/images/brand/graph-memory-hosts-banner.png" alt="Graph Memory for DeepSeek Harness, compatible with OpenClaw" width="100%">
</p>

<p align="center">
  <strong>Bound the context. Keep the memory.</strong><br>
  A native DeepSeek Harness memory plugin that keeps recent conversation turns, archives older history, and recalls exact source-backed knowledge when it matters.
</p>

<p align="center">
  <a href="README_CN.md">中文</a> ·
  <a href="https://www.dsh.so/artifact/graph-memory">dsh.so</a> ·
  <a href="benchmarks/dsh-context-takeover/README.md">20-turn benchmark</a> ·
  <a href="docs/DSH_NATIVE_PLAN.md">Architecture</a>
</p>

<p align="center">
  <a href="https://www.dsh.so/artifact/graph-memory"><img src="https://www.dsh.so/badge/graph-memory.svg" alt="dsh.so security badge"></a>
  <a href="https://www.dsh.so/artifact/graph-memory"><img src="https://www.dsh.so/badge/install/graph-memory.svg" alt="dsh.so install badge"></a>
</p>

## The problem it solves

<p align="center">
  <img src="docs/images/context-memory-illustration.webp" alt="Long agent history becomes graph navigation plus a compact recent-turn context" width="100%">
</p>

Graph Memory owns the **model-visible historical surface** without deleting DSH's event log. By default it keeps the newest five completed user turns, removes completed reasoning/tool traces from future requests, and recalls relevant older or cross-session source Q/A automatically.

## Measured first

<p align="center">
  <img src="docs/images/dsh-context-takeover-chart.svg" alt="DSH 20-turn first-request context comparison" width="100%">
</p>

| Real 20-turn GLM-5.2 run | Native DSH | DSH + Graph Memory | Change |
|---|---:|---:|---:|
| T20 first request | 56,998 tokens | **16,769 tokens** | **−70.58%** |
| T20 model-visible messages | 171 | **24** | **−85.96%** |
| T01–T20 first-request context | 532,451 tokens | **257,656 tokens** | **−51.61%** |
| All measured tokens¹ | 2,487,776 | **2,401,512** | **−3.47%** |

<sub>¹ Includes nondeterministic main-agent tool loops, 20 graph extractions, and 125 embedding requests. Context ownership is the direct adapter metric; the full bill is shown to avoid overstating savings.</sub>

**20/20** scenario turns passed · **19/20** structured extractions succeeded · **42** nodes · **55** edges · **42** vectors · cross-session final facts recalled without `gm_search`.

[Read the Markdown benchmark, per-turn data, method, and limits →](benchmarks/dsh-context-takeover/README.md)

## Memory survives the context window

<p align="center">
  <img src="docs/images/dsh/plugin-inventory-active.png" alt="Graph Memory active in DSH" width="48%">
  <img src="docs/images/dsh/vector-cross-session-recall.png" alt="Cross-session recall in a fresh DSH session" width="48%">
</p>

The graph is a **navigation layer**, not a replacement for evidence. `TASK`, `SKILL`, and `EVENT` nodes point back to the original user question and final visible answer; recalled context includes those exact source messages.

## Install on DeepSeek Harness

Node.js `22.13+` · no DSH fork · current beta installs directly from GitHub:

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

Confirm that `graph-memory/dsh` is active under **Settings → Plugins**. The default database is `$DSH_HOME/graph-memory/graph-memory.db`, normally `~/.dsh/graph-memory/graph-memory.db`.

## What ships

| Capability | Implementation |
|---|---|
| Context takeover | Configurable newest-N completed turns; one archive marker replaces the older model surface |
| Lightweight extraction | Only the user question and final answer; strict structured tool contract; no reasoning/tool transcript ingestion |
| Query-first recall | Vector Top-K with FTS5 fallback; exact source Q/A travels with graph hits |
| Durable memory | Local SQLite, stable provenance, cross-session and cross-project recall |
| Failure behavior | Invalid extraction is quarantined; foreground conversation continues; bad data is not repaired or persisted |
| Host support | Native DSH/Cordis adapter; maintained OpenClaw Context Engine adapter |

<details>
<summary><strong>Optional embeddings</strong></summary>

Graph Memory supports OpenAI-compatible embedding endpoints. Without embeddings it falls back to FTS5 and does not block conversation.

```bash
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
```

</details>

<details>
<summary><strong>DSH tools and extraction route</strong></summary>

| Tool | Purpose |
|---|---|
| `gm_status` | Store, extraction, recall, vector, and retention state |
| `gm_search` | Explicit graph-memory search |
| `gm_record` | Deterministically persist a `TASK`, `SKILL`, or `EVENT` |
| `gm_stats` | Graph and retention receipts |
| `gm_maintain` | One bounded maintenance tick |
| `gm_retry_extraction` | Explicitly retry quarantined extraction |

Automatic recall needs no tool call. Extraction may use a dedicated model via `GRAPH_MEMORY_LLM_PROVIDER` and `GRAPH_MEMORY_LLM_MODEL`; optional reasoning and output controls are `GRAPH_MEMORY_LLM_REASONING_EFFORT` and `GRAPH_MEMORY_LLM_MAX_TOKENS`.

</details>

<details>
<summary><strong>OpenClaw compatibility</strong></summary>

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

Activate the Context Engine slot in `~/.openclaw/openclaw.json`:

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

<p align="center">
  <img src="docs/images/token-comparison.png" alt="Earlier OpenClaw seven-turn token comparison" width="76%">
</p>

</details>

<details>
<summary><strong>Graph Memory Pro</strong></summary>

The repository also contains an experimental read-only DSH Pro Lite Host + Client plugin backed by Community SQLite. The 2D/3D graph workbench, split view, and controlled drag-to-context remain planned. See [`dsh-pro/README_CN.md`](dsh-pro/README_CN.md).

</details>

## Verification and limits

Current beta `1.6.0-beta.13` passes **124/124 automated tests**, both TypeScript builds, npm package verification, and a clean-profile install/boot on official DSH `0.1.3-alpha.1` (`d347e70390`).

- Structured extraction still depends on model contract compliance: the measured run succeeded 19/20 times; failures stay quarantined and never block the foreground conversation.
- Recall is bounded by configurable Top-K. Focused probes succeeded; one broad multi-topic query can require a larger Top-K or separate questions.
- The published run is an engineering workload, not a universal LoCoMo/LongMemEval score.

Reproduce it from [`benchmarks/dsh-context-takeover/`](benchmarks/dsh-context-takeover/). Raw conversations, provider responses, local paths, and credentials are excluded.

## Development

```bash
npm install
npm test
npm run build
npm run verify:package
```

[MIT](LICENSE) © 2026 adoresever · [Asset and trademark notes](docs/ATTRIBUTIONS.md)