# adoresever/graph-memory architecture

> Architecture diagram of the GitHub repository adoresever/graph-memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adoresever/graph-memory
- Repository: https://github.com/adoresever/graph-memory

## Overview

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: [`src/store/store.ts`](https://github.com/adoresever/graph-memory/blob/main/src/store/store.ts) (Graph store), [`src/recaller/recall.ts`](https://github.com/adoresever/graph-memory/blob/main/src/recaller/recall.ts) (Recall engine), [`index.ts`](https://github.com/adoresever/graph-memory/blob/main/index.ts) (Plugin entry), [`src/graph/maintenance.ts`](https://github.com/adoresever/graph-memory/blob/main/src/graph/maintenance.ts) (Maintenance loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Plugin runtime"]
  node_plugin_entry["Plugin entry<br/>openclaw plugin<br/>[index.ts]"]
  node_plugin_manifest["Plugin manifest<br/>openclaw config"]
  node_llm_client["LLM client<br/>api adapter<br/>[llm.ts]"]
  node_embed_client["Embedding client<br/>api adapter<br/>[embed.ts]"]
end

subgraph group_persistence["Persistence"]
  node_store[("Graph store<br/>sqlite store<br/>[store.ts]")]
  node_db[("SQLite DB<br/>sqlite schema<br/>[db.ts]")]
  node_messages["Messages<br/>raw log"]
  node_graph_nodes{{"Nodes & edges<br/>property graph"}}
  node_fts_vectors[("Search indexes<br/>fts + vectors")]
  node_communities[("Communities<br/>cluster summaries")]
end

subgraph group_memory["Memory pipeline"]
  node_extractor["Extractor<br/>llm extraction<br/>[extract.ts]"]
  node_dedup["Deduplication<br/>graph merge<br/>[dedup.ts]"]
  node_pagerank["PageRank<br/>ranking<br/>[pagerank.ts]"]
  node_community["Community detection<br/>clusterer<br/>[community.ts]"]
  node_maintenance["Maintenance loop<br/>orchestrator<br/>[maintenance.ts]"]
  node_recall["Recall engine<br/>retrieval<br/>[recall.ts]"]
end

subgraph group_assembly["Prompt assembly"]
  node_assemble["Context assembler<br/>prompt shaping<br/>[assemble.ts]"]
  node_repair["Transcript repair<br/>normalizer"]
end

node_plugin_manifest -->|"loads"| node_plugin_entry
node_plugin_entry -->|"initializes"| node_store
node_plugin_entry -->|"hooks turns"| node_extractor
node_plugin_entry -->|"serves context"| node_recall
node_plugin_entry -->|"schedules"| node_maintenance
node_store -->|"uses"| node_db
node_store -->|"persists"| node_messages
node_store -->|"persists"| node_graph_nodes
node_store -->|"indexes"| node_fts_vectors
node_store -->|"stores"| node_communities
node_extractor -->|"calls"| node_llm_client
node_extractor -->|"writes facts"| node_store
node_maintenance -->|"orchestrates"| node_dedup
node_maintenance -->|"orchestrates"| node_pagerank
node_maintenance -->|"orchestrates"| node_community
node_dedup -->|"uses"| node_embed_client
node_community -->|"uses"| node_embed_client
node_recall -->|"reads"| node_store
node_recall -->|"ranks"| node_pagerank
node_recall -->|"searches"| node_embed_client
node_recall -->|"expands"| node_community
node_recall -->|"returns"| node_assemble
node_assemble -->|"normalizes"| node_repair
node_assemble -->|"hydrates"| node_store
node_assemble -->|"includes recall"| node_recall
node_llm_client -.->|"supports"| node_extractor
node_embed_client -.->|"powers"| node_fts_vectors

click node_plugin_entry "https://github.com/adoresever/graph-memory/blob/main/index.ts"
click node_plugin_manifest "https://github.com/adoresever/graph-memory/blob/main/openclaw.plugin.json"
click node_llm_client "https://github.com/adoresever/graph-memory/blob/main/src/engine/llm.ts"
click node_embed_client "https://github.com/adoresever/graph-memory/blob/main/src/engine/embed.ts"
click node_store "https://github.com/adoresever/graph-memory/blob/main/src/store/store.ts"
click node_db "https://github.com/adoresever/graph-memory/blob/main/src/store/db.ts"
click node_extractor "https://github.com/adoresever/graph-memory/blob/main/src/extractor/extract.ts"
click node_dedup "https://github.com/adoresever/graph-memory/blob/main/src/graph/dedup.ts"
click node_pagerank "https://github.com/adoresever/graph-memory/blob/main/src/graph/pagerank.ts"
click node_community "https://github.com/adoresever/graph-memory/blob/main/src/graph/community.ts"
click node_maintenance "https://github.com/adoresever/graph-memory/blob/main/src/graph/maintenance.ts"
click node_recall "https://github.com/adoresever/graph-memory/blob/main/src/recaller/recall.ts"
click node_assemble "https://github.com/adoresever/graph-memory/blob/main/src/format/assemble.ts"
click node_repair "https://github.com/adoresever/graph-memory/blob/main/src/format/transcript-repair.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_entry,node_plugin_manifest,node_llm_client,node_embed_client toneBlue
class node_store,node_db,node_messages,node_graph_nodes,node_fts_vectors,node_communities toneAmber
class node_extractor,node_dedup,node_pagerank,node_community,node_maintenance,node_recall toneMint
class node_assemble,node_repair toneRose
```

## Components

### Plugin runtime

OpenClaw plugin entry and configuration boundary.

- [Plugin entry](https://github.com/adoresever/graph-memory/blob/main/index.ts): openclaw plugin · Loads the memory plugin into OpenClaw and anchors the runtime boundary. · `index.ts`
- [Plugin manifest](https://github.com/adoresever/graph-memory/blob/main/openclaw.plugin.json): openclaw config · Declares how OpenClaw loads and activates the plugin. · `openclaw.plugin.json`
- [LLM client](https://github.com/adoresever/graph-memory/blob/main/src/engine/llm.ts): api adapter · Raw fetch-based LLM integration for OpenAI-compatible endpoints. · `src/engine/llm.ts`
- [Embedding client](https://github.com/adoresever/graph-memory/blob/main/src/engine/embed.ts): api adapter · 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](https://github.com/adoresever/graph-memory/blob/main/src/store/store.ts): sqlite store · Main database boundary for messages, nodes, edges, signals, communities, vectors, and FTS. · `src/store/store.ts`
- [SQLite DB](https://github.com/adoresever/graph-memory/blob/main/src/store/db.ts): sqlite schema · Durable database implementation and schema access layer. · `src/store/db.ts`
- **Messages**: raw log · Persisted conversation turns used as the source for later extraction and recall.
- **Nodes & edges**: property graph · Typed knowledge graph facts extracted from conversation and stored durably.
- **Search indexes**: fts + vectors · Full-text and optional semantic indexes for retrieval and deduplication.
- **Communities**: cluster summaries · Community memberships, summaries, and embeddings used for generalized recall.

### Memory pipeline

Extraction, maintenance, recall, and graph algorithms that transform conversation into durable memory.

- [Extractor](https://github.com/adoresever/graph-memory/blob/main/src/extractor/extract.ts): llm extraction · Transforms conversation text into structured TASK, SKILL, and EVENT facts. · `src/extractor/extract.ts`
- [Deduplication](https://github.com/adoresever/graph-memory/blob/main/src/graph/dedup.ts): graph merge · Merges near-duplicate nodes using vector similarity. · `src/graph/dedup.ts`
- [PageRank](https://github.com/adoresever/graph-memory/blob/main/src/graph/pagerank.ts): ranking · Personalized PageRank scorer for recall and graph traversal. · `src/graph/pagerank.ts`
- [Community detection](https://github.com/adoresever/graph-memory/blob/main/src/graph/community.ts): clusterer · Finds graph communities and produces summaries for broader recall. · `src/graph/community.ts`
- [Maintenance loop](https://github.com/adoresever/graph-memory/blob/main/src/graph/maintenance.ts): orchestrator · Coordinates periodic deduplication, ranking, and clustering cycles. · `src/graph/maintenance.ts`
- [Recall engine](https://github.com/adoresever/graph-memory/blob/main/src/recaller/recall.ts): retrieval · 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](https://github.com/adoresever/graph-memory/blob/main/src/format/assemble.ts): prompt shaping · Builds the final context payload from retrieved graph state and recent messages. · `src/format/assemble.ts`
- [Transcript repair](https://github.com/adoresever/graph-memory/blob/main/src/format/transcript-repair.ts): normalizer · Sanitizes and normalizes malformed transcript shapes before prompt assembly. · `src/format/transcript-repair.ts`

## Connections

- 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.
