Memory Graph Builder

Memory Graph Builder

What it does

OpenClaw stores agent memory in a flat MEMORY.md file — one line per fact, no structure, no relationships. This works until your agent has 200+ memories and half of them are duplicates, three contradict each other, and the whole file costs 4,000 tokens every session.

Memory Graph Builder treats MEMORY.md as a raw data source and builds a structured knowledge graph on top of it. Each memory becomes a node with typed relationships to other nodes. The graph enables:

• Duplicate detection — "User prefers dark mode" and "User likes dark theme" are the same fact
• Contradiction detection — "User uses Python 3.8" vs "User uses Python 3.12"
• Staleness detection — Facts older than a configurable threshold that haven't been referenced
• Memory digest — A compressed, relationship-aware summary that replaces raw MEMORY.md in the system prompt, saving 30-60% tokens

Inspired by OpenLobster's Neo4j-backed graph memory system, adapted to work on top of OpenClaw's existing MEMORY.md without requiring a database.

When to invoke

• Automatically, nightly at 10pm (cron)
• After bulk memory additions (e.g., after project-onboarding)
• When the agent's context initialisation feels slow (memory bloat)
• Manually to audit memory quality

Graph structure

Each memory line becomes a node:

yamlCopy code
nodes:
  - id: "mem_001"
    text: "User prefers Python for backend work"
    category: preference    # preference | fact | project | person | tool | config
    entities: ["user", "python", "backend"]
    added_at: "2026-03-01"
    last_referenced: "2026-03-15"
    confidence: 0.9
edges:
  - from: "mem_001"
    to: "mem_014"
    relation: related_to    # related_to | contradicts | supersedes | depends_on

How to use

bashCopy code
python3 graph.py --build                    # Parse MEMORY.md, build graph
python3 graph.py --duplicates               # Show duplicate clusters
python3 graph.py --contradictions           # Show contradicting pairs
python3 graph.py --stale --days 30          # Show memories not referenced in 30 days
python3 graph.py --digest                   # Generate compressed memory digest
python3 graph.py --digest --max-tokens 1500 # Digest with token budget
python3 graph.py --prune --dry-run          # Show what would be removed
python3 graph.py --prune                    # Remove duplicates + stale entries
python3 graph.py --stats                    # Graph statistics
python3 graph.py --status                   # Last build summary
python3 graph.py --format json

Cron wakeup behaviour

Nightly at 10pm:

1. Read MEMORY.md
2. Rebuild graph (incremental — only re-processes new/changed lines)
3. Detect duplicates and contradictions
4. Flag stale entries (>30 days unreferenced by default)
5. Generate fresh memory digest
6. Write digest to ~/.openclaw/workspace/memory-digest.md
7. Log summary to state

Memory digest

The digest is a compressed representation of the knowledge graph optimized for LLM consumption. Instead of dumping every raw line, it:

• Groups related memories by category
• Merges duplicate facts into single entries
• Marks contradictions with [CONFLICT] so the agent can resolve them
• Omits stale entries below a confidence threshold
• Respects a configurable max-token budget

Example digest output:

markdownCopy code
## Preferences
- Prefers Python for backend, TypeScript for frontend
- Dark mode everywhere; compact UI layouts
- Commit messages: imperative mood, max 72 chars

## Active Projects
- openclaw-superpowers: skill library, 40 skills, MIT license
- personal-site: Next.js 14, deployed on Vercel

## People
- Alice (teammate): works on auth, prefers Go

## Conflicts (needs resolution)
- [CONFLICT] Python version: "3.8" vs "3.12" — ask user to clarify

Procedure

Step 1 — Build the graph

bashCopy code
python3 graph.py --build

Step 2 — Review duplicates and contradictions

bashCopy code
python3 graph.py --duplicates
python3 graph.py --contradictions

Fix contradictions by editing MEMORY.md directly or asking the agent to clarify.

Step 3 — Prune stale entries

bashCopy code
python3 graph.py --prune --dry-run
python3 graph.py --prune

Step 4 — Generate and use the digest

bashCopy code
python3 graph.py --digest --max-tokens 1500

Point OpenClaw's memory injection at ~/.openclaw/workspace/memory-digest.md instead of raw MEMORY.md.

State

Graph structure, digest cache, and audit history stored in ~/.openclaw/skill-state/memory-graph-builder/state.yaml.

Fields: last_build_at, node_count, edge_count, duplicate_count, contradiction_count, stale_count, digest_tokens, build_history.