Tools
Graph Memory
By Openclaw记忆插件Knowledge Graph + Memory；Knowledge Graph Context Engine for OpenClaw — extracts structured triples from conversations, compresses context 75%, enables cross-session experience reuse
Install
npm install
npxConfiguration Example
{
"plugins": {
"slots": {
"contextEngine": "graph-memory"
},
"entries": {
"graph-memory": {
"enabled": true
}
}
}
}README
<p align="center">
<img src="docs/images/banner.jpg" alt="graph-memory" width="100%" />
</p>
<h1 align="center">graph-memory</h1>
<p align="center">
<strong>Knowledge Graph Context Engine for OpenClaw</strong><br>
By <a href="mailto:[email protected]">adoresever</a> · MIT License
</p>
<p align="center">
<a href="#installation">Installation</a> ·
<a href="#how-it-works">How it works</a> ·
<a href="#configuration">Configuration</a> ·
<a href="README_CN.md">中文文档</a>
</p>
---
<p align="center">
<img src="docs/images/hero.png" alt="graph-memory overview" width="90%" />
</p>
## What it does
When conversations grow long, agents lose track of what happened. graph-memory solves three problems at once:
1. **Context explosion** — 174 messages eat 95K tokens. graph-memory compresses to ~24K by replacing raw history with structured knowledge graph nodes
2. **Cross-session amnesia** — Yesterday's bugs, solved problems, all gone in a new session. graph-memory recalls relevant knowledge automatically via FTS5/vector search + graph traversal
3. **Skill islands** — Self-improving agents record learnings as isolated markdown. graph-memory connects them: "installed libgl1" and "ImportError: libGL.so.1" are linked by a `SOLVED_BY` edge
**It feels like talking to an agent that learns from experience. Because it does.**
<p align="center">
<img src="docs/images/graph-ui.png" alt="graph-memory knowledge graph visualization with community detection" width="95%" />
</p>
> *58 nodes, 40 edges, 3 communities — automatically extracted from conversations. Right panel shows the knowledge graph with community clusters (GitHub ops, B站 MCP, session management). Left panel shows agent using `gm_stats` and `gm_search` tools.*
## What's new in v2.0
### Community-aware recall
Recall now runs **two parallel paths** that merge results:
- **Precise path**: vector/FTS5 search → community expansion → graph walk → PPR ranking
- **Generalized path**: query vector vs community summary embeddings → community members → PPR ranking
Community summaries are generated immediately after each community detection cycle (every 7 turns), so the generalized path is available from the first maintenance window.
### Episodic context (conversation traces)
The top 3 PPR-ranked nodes now pull their **original user/assistant conversation snippets** into the context. The agent sees not just structured triples, but the actual dialogue that produced them — improving accuracy when reapplying past solutions.
### Universal embedding support
The embedding module now uses raw `fetch` instead of the `openai` SDK, making it compatible with **any OpenAI-compatible endpoint** out of the box:
- OpenAI, Azure OpenAI
- Alibaba DashScope (`text-embedding-v4`)
- MiniMax (`embo-01`)
- Ollama, llama.cpp, vLLM (local models)
- Any endpoint that implements `POST /embeddings`
### Windows one-click installer
v2.0 ships a **Windows installer** (`.exe`). Download from [Releases](https://github.com/adoresever/graph-memory/releases):
1. Download `graph-memory-installer-win-x64.exe`
2. Run the installer — it auto-detects your OpenClaw installation
3. The installer configures `plugins.slots.contextEngine`, adds the plugin entry, and restarts the gateway
## Real-world results
<p align="center">
<img src="docs/images/token-comparison.png" alt="Token comparison: 7 rounds" width="85%" />
</p>
7-round conversation installing bilibili-mcp + login + query:
| Round | Without graph-memory | With graph-memory |
|-------|---------------------|-------------------|
| R1 | 14,957 | 14,957 |
| R4 | 81,632 | 29,175 |
| R7 | **95,187** | **23,977** |
**75% compression.** Red = linear growth without graph-memory. Blue = stabilized with graph-memory.
<p align="center">
<img src="docs/images/token-sessions.png" alt="Cross-session recall" width="85%" />
</p>
## How it works
### The Knowledge Graph
graph-memory builds a typed property graph from conversations:
- **3 node types**: `TASK` (what was done), `SKILL` (how to do it), `EVENT` (what went wrong)
- **5 edge types**: `USED_SKILL`, `SOLVED_BY`, `REQUIRES`, `PATCHES`, `CONFLICTS_WITH`
- **Personalized PageRank**: ranks nodes by relevance to the current query, not global popularity
- **Community detection**: automatically groups related skills (Docker cluster, Python cluster, etc.)
- **Community summaries**: LLM-generated descriptions + embeddings for each community, enabling semantic community-level recall
- **Episodic traces**: original conversation snippets linked to graph nodes for faithful context reconstruction
- **Vector dedup**: merges semantically duplicate nodes via cosine similarity
### Dual-path recall
```
User query
│
├─ Precise path (entity-level)
│ vector/FTS5 search → seed nodes
│ → community peer expansion
│ → graph walk (N hops)
│ → Personalized PageRank ranking
│
├─ Generalized path (community-level)
│ query embedding vs community summary embeddings
│ → matched community members
│ → graph walk (1 hop)
│ → Personalized PageRank ranking
│
└─ Merge & deduplicate → final context
```
Both paths run in parallel. Precise results take priority; generalized results fill gaps from uncovered knowledge domains.
### Data flow
```
Message in → ingest (zero LLM)
├─ All messages saved to gm_messages
└─ turn_index continues from DB max (survives gateway restart)
assemble (zero LLM)
├─ Graph nodes → XML with community grouping (systemPromptAddition)
├─ PPR ranking decides injection priority
├─ Episodic traces for top 3 nodes
├─ Content normalization (prevents OpenClaw content.filter crash)
└─ Keep last turn raw messages
afterTurn (async, non-blocking)
├─ LLM extracts triples → gm_nodes + gm_edges
├─ Every 7 turns: PageRank + community detection + community summaries
└─ User sends new message → extract auto-interrupted
session_end
├─ finalize (LLM): EVENT → SKILL promotion
└─ maintenance: dedup → PageRank → community detection
Next session → before_prompt_build
├─ Dual-path recall (precise + generalized)
└─ Personalized PageRank ranking → inject into context
```
### Personalized PageRank (PPR)
Unlike global PageRank, PPR ranks nodes **relative to your current query**:
- Ask about "Docker deployment" → Docker-related SKILLs rank highest
- Ask about "conda environment" → conda-related SKILLs rank highest
- Same graph, completely different rankings per query
- Computed in real-time at recall (~5ms for thousands of nodes)
## Installation
### Prerequisites
- [OpenClaw](https://github.com/openclaw/openclaw) (v2026.3.x+)
- Node.js 22+
### Windows users
Download the installer from [Releases](https://github.com/adoresever/graph-memory/releases):
```
graph-memory-installer-win-x64.exe
```
The installer handles everything: plugin installation, context engine activation, and gateway restart. After running, skip to [Step 3: Configure LLM and Embedding](#step-3-configure-llm-and-embedding).
### Step 1: Install the plugin
Choose one of three methods:
**Option A — From npm registry** (recommended):
```bash
pnpm openclaw plugins install graph-memory
```
No `node-gyp`, no manual compilation. The SQLite driver (`@photostructure/sqlite`) ships prebuilt binaries — works with OpenClaw's `--ignore-scripts` install.
**Option B — From GitHub**:
```bash
pnpm openclaw plugins install github:adoresever/graph-memory
```
**Option C — From source** (for development or custom modifications):
```bash
git clone https://github.com/adoresever/graph-memory.git
cd graph-memory
npm install
npx vitest run # verify 80 tests pass
pnpm openclaw plugins install .
```
### Step 2: Activate context engine
This is the **critical step** most people miss. graph-memory must be registered as the context engine, otherwise OpenClaw will only use it for recall but **won't ingest messages or extract knowledge**.
Edit `~/.openclaw/openclaw.json` and add `plugins.slots`:
```json
{
"plugins": {
"slots": {
"contextEngine": "graph-memory"
},
"entries": {
"graph-memory": {
"enabled": true
}
}
}
}
```
Without `"contextEngine": "graph-memory"` in `plugins.slots`, the plugin registers but the `ingest` / `assemble` / `compact` pipeline never fires — you'll see `recall` in logs but zero data in the database.
### Step 3: Configure LLM and Embedding
Add your API credentials inside `plugins.entries.graph-memory.config`:
```json
{
"plugins": {
"slots": {
"contextEngine": "graph-memory"
},
"entries": {
"graph-memory": {
"enabled": true,
"config": {
"llm": {
"apiKey": "your-llm-api-key",
"baseURL": "https://api.openai.com/v1",
"model": "gpt-4o-mini"
},
"embedding": {
"apiKey": "your-embedding-api-key",
"baseURL": "https://api.openai.com/v1",
"model": "text-embedding-3-small",
"dimensions": 512
}
}
}
}
}
}
```
**LLM** (`config.llm`) — Required. Used for knowledge extraction and community summaries. Any OpenAI-compatible endpoint works. Use a cheap/fast model.
**Embedding** (`config.embedding`) — Optional but recommended. Enables semantic vector search, community-level recall, and vector dedup. Without it, falls back to FTS5 full-text search (still works, just keyword-based).
> **⚠️ Important**: `pnpm openclaw plugins install` may reset your config. Always verify `config.llm` and `config.embedding` are present after reinstalling.
If `config.llm` is not set, graph-memory falls back to the `ANTHROPIC_API_KEY` environment variable + Anthropic API.
### Supported embedding providers
| Provider | baseURL | Model | dimensions |
|----------|---------|-------|------------|
| OpenAI | `https://api.openai.com/v1` | `text-embedding-3-small` | 512 |
| Alibaba DashScope | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `text-embedding-v4` | 1024 |
... (truncated)
tools
Comments
Sign in to leave a comment