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

(: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

# 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:

{
  "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:

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