Tools

Neo4j Context Engine

Name: Neo4j Context Engine
Rating: 3.5 (1 reviews)
Author: ArielleTolome

By ArielleTolome 👁 69 views ▲ 0 votes

OpenClaw Context Engine plugin using Neo4j + Qdrant instead of local SQLite. Cross-agent DAG-based conversation storage.

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": {
    "allow": ["neo4j-context-engine"],
    "entries": {
      "neo4j-context-engine": {
        "enabled": true,
        "neo4jUrl": "neo4j://your-neo4j-host:7687",
        "neo4jUsername": "neo4j",
        "neo4jPassword": "your-password",
        "qdrantUrl": "http://your-qdrant-host:6333",
        "qdrantApiKey": "your-qdrant-api-key",
        "openaiApiKey": "sk-...",
        "contextThreshold": 0.75,
        "freshTailCount": 6,
        "summaryCollection": "context-summaries"
      }
    }
  }
}

README

# neo4j-context-engine

An OpenClaw Context Engine plugin that replaces local SQLite (lossless-claw) with a shared **Neo4j + Qdrant** backend — enabling cross-agent conversation DAG storage accessible by your entire agent fleet.

Built on the Context Engine plugin slot introduced in OpenClaw **v2026.3.7**.

## What it does

- **Every message** is stored as a Neo4j node, chained in session order
- **On compaction**: summarizes old messages via OpenAI, stores Summary nodes in a DAG (`SUMMARIZED_BY` / `CHILD_OF` relationships), indexes summary embeddings in Qdrant
- **On assemble**: retrieves the right messages + summaries from Neo4j to fit within the token budget
- **Cross-agent**: all agents share the same Neo4j instance — query any agent's conversation history from anywhere

## Architecture

```
Conversation turn
    ↓ ingest()
Neo4j :Message node → linked via :NEXT chain

Context window full
    ↓ compact()
OpenAI gpt-4.1-mini summarizes chunk
    ↓
Neo4j :Summary node → linked via :SUMMARIZED_BY + :CHILD_OF (DAG)
Qdrant "context-summaries" → summary embedding for semantic search

Next turn
    ↓ assemble()
Neo4j → fetch messages + latest summary → fit within token budget
```

## Neo4j Schema

```cypher
(:Session   { id, agentId, createdAt })
(:Message   { id, sessionId, agentId, role, content, estimatedTokens, createdAt, seq })
(:Summary   { id, sessionId, agentId, content, estimatedTokens, messageCount, depth, createdAt, qdrantId })

(:Session)-[:HAS_MESSAGE]->(:Message)
(:Message)-[:NEXT { sessionId }]->(:Message)
(:Message)-[:SUMMARIZED_BY]->(:Summary)
(:Summary)-[:CHILD_OF]->(:Summary)
(:Session)-[:SPAWNED]->(:Session)
```

## Requirements

- OpenClaw v2026.3.7+
- Neo4j 5.x instance (self-hosted or AuraDB)
- Qdrant instance (self-hosted or cloud)
- OpenAI API key (for summarization + embeddings)

## Installation

```bash
# Clone into your OpenClaw extensions directory
git clone https://github.com/arieltolome/neo4j-context-engine \
  ~/.openclaw/extensions/neo4j-context-engine

cd ~/.openclaw/extensions/neo4j-context-engine
npm install
```

## Configuration

Add to your `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "allow": ["neo4j-context-engine"],
    "entries": {
      "neo4j-context-engine": {
        "enabled": true,
        "neo4jUrl": "neo4j://your-neo4j-host:7687",
        "neo4jUsername": "neo4j",
        "neo4jPassword": "your-password",
        "qdrantUrl": "http://your-qdrant-host:6333",
        "qdrantApiKey": "your-qdrant-api-key",
        "openaiApiKey": "sk-...",
        "contextThreshold": 0.75,
        "freshTailCount": 6,
        "summaryCollection": "context-summaries"
      }
    }
  }
}
```

Alternatively, set environment variables:

| Env var | Description |
|---|---|
| `NEO4J_URL` | e.g. `neo4j://localhost:7687` |
| `NEO4J_USERNAME` | default: `neo4j` |
| `NEO4J_PASSWORD` | required |
| `QDRANT_URL` | e.g. `http://localhost:6333` |
| `QDRANT_API_KEY` | optional if Qdrant has no auth |
| `OPENAI_API_KEY` | required |

Then restart the gateway:

```bash
openclaw gateway restart
```

## Config options

| Option | Default | Description |
|---|---|---|
| `contextThreshold` | `0.75` | Fraction of token budget that triggers compaction |
| `freshTailCount` | `6` | Number of recent messages protected from compaction |
| `summaryCollection` | `"context-summaries"` | Qdrant collection name for summary embeddings |

## vs lossless-claw

| | lossless-claw | neo4j-context-engine |
|---|---|---|
| Storage | Local SQLite (per machine) | Shared Neo4j (all agents) |
| Cross-agent visibility | ❌ | ✅ |
| Semantic search over history | ❌ | ✅ (Qdrant) |
| DAG traversal queries | Limited | Full Cypher |
| Zero information loss | ✅ | ✅ |

## License

MIT

tools