The Problem
Long-running agent conversations hit two walls. First, context windows fill with raw history — the README documents 174 messages consuming 95K tokens, which degrades performance and raises cost. Second, knowledge dies with the session: solved bugs and installed dependencies are forgotten, forcing agents to re-derive solutions. The repo addresses both by converting conversation history into a structured knowledge graph that persists across sessions.
What This Does
graph-memory is a context engine plugin for OpenClaw. It extracts typed triples from conversation text (src/extractor/extract.ts), stores them in SQLite with FTS5 and vector indexes (src/store/db.ts), and runs graph algorithms for retrieval. The src/graph/ directory contains pagerank.ts for node ranking, community.ts for cluster detection, and dedup.ts for entity merging. Recall merges two paths—precise vector/FTS5 search and generalized community summaries—via src/recaller/recall.ts. The system claims 75% token compression by replacing raw history with graph nodes plus episodic context snippets.
The v2.0 feature set includes community-aware recall, conversation trace injection, and universal embedding support via raw fetch calls to any OpenAI-compatible endpoint (src/engine/embed.ts).
How To Use It
Installation requires adding the plugin to an existing OpenClaw installation. The README references a Windows installer; for other platforms, you'd configure plugins.slots.contextEngine in OpenClaw's config and add the plugin entry. The openclaw.plugin.json file defines the plugin manifest.
From the repo root, install dependencies and build
npm install npm run build
Run tests
npx vitest run
Configuration is done through OpenClaw's plugin system, not a standalone config file in this repo. The plugin exposes gmstats and gmsearch tools that the agent calls at runtime. Embedding endpoints are configured via environment variables or OpenClaw settings—the exact variable names aren't documented in the README excerpt, so check src/engine/embed.ts for the expected configuration keys.
Real-World Use
An agent debugging a Python environment issue: it encounters ImportError: libGL.so.1, installs libgl1, and the fix is recorded as a triple. In a later session, when the same error appears, gmsearch retrieves the node and its SOLVEDBY edge, pulling the original conversation snippet into context. The agent applies the fix without re-searching. The README's benchmark shows a 7-round session stabilizing at ~24K tokens versus ~95K without the plugin.
Code Health & Issues
Med - No CI/CD pipeline - No .github/ directory or CI config detected. Build and test gates aren't automated. Low - No lockfile - package.json exists without package-lock.json or pnpm-lock.yaml, making builds non-reproducible. Low - Single maintainer - The repo is forked from adoresever/graph-memory (507 stars) but this fork shows 0 stars. Verify the fork is current with upstream before relying on it. Med - Error handling in embedding - src/engine/embed.ts uses raw fetch for universal compatibility. Failed requests, rate limits, and timeouts need explicit handling; verify these paths in the code. Low - Test coverage breadth - 7 test files cover extraction, graph operations, store, and recall, but no tests for the embedding module or LLM integration (src/engine/llm.ts).
The Bottom Line
This is a practical solution to a real problem—context window exhaustion in agent conversations—with measurable results and a reasonable architecture. The graph-based approach is more sophisticated than simple summarization and the community detection adds useful retrieval semantics. The lack of CI and lockfile are minor concerns for a plugin, but the single-maintainer risk and the need to verify the fork's divergence from the original are worth checking before production use. Suitable for teams running OpenClaw agents at scale who need persistent memory across sessions.