How adoresever/graph-memory works
1. Overall shape
- This repo is an OpenClaw context-engine plugin that turns conversation history into a SQLite-backed knowledge graph and then re-injects relevant graph context into future prompts.
- The main runtime boundary is the OpenClaw gateway/plugin lifecycle: the plugin participates in ingestion, post-turn extraction, prompt assembly, recall, and maintenance.
2. Plugin entry and configuration boundary
- index.ts is the top-level plugin entry, with openclaw.plugin.json defining how OpenClaw loads it.
- The repo is designed to run inside Node.js 22+ and depends on OpenClaw being configured with plugins.slots.contextEngine = "graph-memory"; without that, it may load as a plugin but not act as the active context engine.
3. Persistence layer
- src/store/ encapsulates all database access using SQLite via @photostructure/sqlite.
- The database is the system of record for:
- gm_messages raw chat messages
- gm_nodes knowledge nodes
- gm_edges typed graph relationships
- gm_nodes_fts full-text index
- gm_vectors optional embedding vectors
- gm_communities community summaries and embeddings
- gm_signals detected signals
- This layer is the main boundary between durable state and the rest of the engine.
4. Ingestion path
- Conversation messages are saved first, with no LLM call on the hot path.
- The repo preserves a turn_index across restarts by reading from the DB, which makes the pipeline resilient to gateway restarts and keeps extraction/maintenance aligned with actual conversation order.
5. Knowledge extraction path
- src/extractor/ handles the LLM-driven transformation from conversation text into structured graph facts.
- The extracted model is a typed property graph centered on three node kinds: TASK, SKILL, and EVENT.
- Edges encode meaning such as USED_SKILL, SOLVED_BY, REQUIRES, PATCHES, and CONFLICTS_WITH.
- This path runs after turns and is intentionally asynchronous/non-blocking.
6. Graph maintenance subsystem
- src/graph/ contains the graph algorithms that keep the knowledge base usable over time:
- dedup.ts merges near-duplicate nodes using vector similarity
- pagerank.ts computes Personalized PageRank
- community.ts detects communities and generates summaries
- maintenance.ts orchestrates maintenance cycles
- Maintenance is triggered periodically, especially every compactTurnCount turns and at session end.
7. Recall subsystem
- src/recaller/recall.ts implements the main retrieval logic.
- Recall has two parallel routes:
- Precise path: seed from FTS/vector search, expand via community peers, walk the graph, rank with Personalized PageRank
- Generalized path: compare the query embedding to community-summary embeddings, then retrieve members of the matched communities and rank them
- The two paths are merged and deduplicated to produce the final context set.
8. Prompt assembly and context shaping
- src/format/assemble.ts is responsible for turning retrieved graph state and recent conversation into the context OpenClaw will send onward.
- It injects graph nodes as structured context, groups them by community, preserves the last turn as raw messages, and includes episodic traces for the top-ranked nodes so the model sees the original conversation snippets behind the graph facts.
- src/format/transcript-repair.ts and related normalization logic protect OpenClaw from malformed content shapes.
9. Model/embedding integration
- src/engine/llm.ts and src/engine/embed.ts are intentionally SDK-light and use raw fetch.
- This makes the repo compatible with any OpenAI-compatible API endpoint for embeddings and LLM calls, including local or hosted providers.
- Embeddings are optional but materially change architecture: when enabled, they power semantic search, community recall, and vector dedup; when absent, the system falls back to FTS5 keyword search.
10. Agent-facing tools
- The plugin exposes tools for operational interaction with the graph:
- gm_search for retrieval
- gm_record for manual writes
- gm_stats for graph visibility
- gm_maintain for manual maintenance
- These tools sit on top of the same store/graph subsystems rather than bypassing them.
11. Key data flow
- The core flow is: message in → persist raw message → later extract nodes/edges → periodically dedup + rank + cluster → future query recall → assemble prompt context.
- That means the repo is not just a retriever; it is a continuously updated memory system with both short-term conversation storage and long-term graph memory.
12. Testing and confidence boundaries
- test/ covers the main subsystems separately: store, extract, assemble, recall/community logic, and graph maintenance.
- The test layout mirrors the architecture, which is a good indicator that these are the primary stable boundaries of the system.
Main entry points: store.ts Graph store · recall.ts Recall engine · index.ts Plugin entry · maintenance.ts Maintenance loop
Components 18
Plugin runtime
OpenClaw plugin entry and configuration boundary.
- Plugin entry · Loads the memory plugin into OpenClaw and anchors the runtime boundary.
index.ts - Plugin manifest · Declares how OpenClaw loads and activates the plugin.
openclaw.plugin.json - LLM client · Raw fetch-based LLM integration for OpenAI-compatible endpoints.
src/engine/llm.ts - Embedding client · Optional embedding integration used by recall, dedup, and community logic.
src/engine/embed.ts
Persistence
SQLite-backed system of record for messages, graph state, and embeddings.
- Graph store · Main database boundary for messages, nodes, edges, signals, communities, vectors, and FTS.
src/store/store.ts - SQLite DB · Durable database implementation and schema access layer.
src/store/db.ts - Messages · Persisted conversation turns used as the source for later extraction and recall.
- Nodes & edges · Typed knowledge graph facts extracted from conversation and stored durably.
- Search indexes · Full-text and optional semantic indexes for retrieval and deduplication.
- Communities · Community memberships, summaries, and embeddings used for generalized recall.
Memory pipeline
Extraction, maintenance, recall, and graph algorithms that transform conversation into durable memory.
- Extractor · Transforms conversation text into structured TASK, SKILL, and EVENT facts.
src/extractor/extract.ts - Deduplication · Merges near-duplicate nodes using vector similarity.
src/graph/dedup.ts - PageRank · Personalized PageRank scorer for recall and graph traversal.
src/graph/pagerank.ts - Community detection · Finds graph communities and produces summaries for broader recall.
src/graph/community.ts - Maintenance loop · Coordinates periodic deduplication, ranking, and clustering cycles.
src/graph/maintenance.ts - Recall engine · Combines precise and generalized graph recall into a final context set.
src/recaller/recall.ts
Prompt assembly
Context shaping and transcript normalization before OpenClaw sends prompts onward.
- Context assembler · Builds the final context payload from retrieved graph state and recent messages.
src/format/assemble.ts - Transcript repair · Sanitizes and normalizes malformed transcript shapes before prompt assembly.
src/format/transcript-repair.ts
Connections 27
- Plugin manifest → Plugin entry: loads · OpenClaw uses the manifest to load the plugin entry point.
- Plugin entry → Graph store: initializes · The plugin wires runtime operations to the persistent store.
- Plugin entry → Extractor: hooks turns · Post-turn processing routes conversation into extraction.
- Plugin entry → Recall engine: serves context · Recall runs during prompt preparation and context injection.
- Plugin entry → Maintenance loop: schedules · Periodic and end-of-session maintenance is coordinated from the plugin lifecycle.
- Graph store → SQLite DB: uses · Store operations are backed by the SQLite database layer.
- Graph store → Messages: persists · Raw conversation messages are recorded before any LLM work.
- Graph store → Nodes & edges: persists · Extracted graph facts are stored as nodes and edges.
- Graph store → Search indexes: indexes · Text search and optional embeddings are maintained for retrieval.
- Graph store → Communities: stores · Cluster membership and summaries are stored durably.
- Extractor → LLM client: calls · Structured facts are produced by LLM-backed extraction.
- Extractor → Graph store: writes facts · Extracted nodes, edges, and signals are persisted.
- Maintenance loop → Deduplication: orchestrates · Maintenance runs duplicate merging as part of graph upkeep.
- Maintenance loop → PageRank: orchestrates · Maintenance refreshes ranking state for later recall.
- Maintenance loop → Community detection: orchestrates · Maintenance clusters the graph and updates community summaries.
- Deduplication → Embedding client: uses · Semantic similarity helps detect near-duplicate nodes.
- Community detection → Embedding client: uses · Community summaries can be embedded for generalized retrieval.
- Recall engine → Graph store: reads · Recall seeds from FTS, vectors, communities, and graph structure.
- Recall engine → PageRank: ranks · Retrieved candidates are refined with Personalized PageRank.
- Recall engine → Embedding client: searches · Semantic search powers precise and generalized retrieval paths.
- Recall engine → Community detection: expands · Matched communities provide broader recall candidates.
- Recall engine → Context assembler: returns · Final ranked context is passed into prompt assembly.
- Context assembler → Transcript repair: normalizes · Transcript shapes are repaired before being emitted.
- Context assembler → Graph store: hydrates · Assembly pulls recent raw messages and graph context from storage.
- Context assembler → Recall engine: includes recall · Assembled prompts include the retrieved graph context set.
- LLM client → Extractor: supports · LLM access powers structured extraction and other model-driven steps.
- Embedding client → Search indexes: powers · Embeddings enrich semantic indexing and search when enabled.