Add memory-graph-builder: knowledge graph from MEMORY.md

skills/openclaw-native/memory-graph-builder/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: memory-graph-builder
+version: "1.0"
+category: openclaw-native
+description: Parses OpenClaw's flat MEMORY.md into a structured knowledge graph — detects duplicates, contradictions, and stale entries, then builds a compressed memory digest optimized for system prompt injection.
+stateful: true
+cron: "0 22 * * *"
+---
+
+# 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:
+
+```yaml
+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
+
+```bash
+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:
+
+```markdown
+## 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**
+
+```bash
+python3 graph.py --build
+```
+
+**Step 2 — Review duplicates and contradictions**
+
+```bash
+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**
+
+```bash
+python3 graph.py --prune --dry-run
+python3 graph.py --prune
+```
+
+**Step 4 — Generate and use the digest**
+
+```bash
+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`.

skills/openclaw-native/memory-graph-builder/STATE_SCHEMA.yaml

@@ -0,0 +1,54 @@
+version: "1.0"
+description: Knowledge graph built from MEMORY.md — nodes, edges, digest, and audit metrics.
+fields:
+  last_build_at:
+    type: datetime
+  node_count:
+    type: integer
+    default: 0
+  edge_count:
+    type: integer
+    default: 0
+  duplicate_count:
+    type: integer
+    default: 0
+  contradiction_count:
+    type: integer
+    default: 0
+  stale_count:
+    type: integer
+    default: 0
+  digest_tokens:
+    type: integer
+    default: 0
+  nodes:
+    type: list
+    description: All memory nodes in the graph
+    items:
+      id:              { type: string }
+      text:            { type: string }
+      category:        { type: enum, values: [preference, fact, project, person, tool, config, other] }
+      entities:        { type: list, items: { type: string } }
+      added_at:        { type: string }
+      last_referenced: { type: string }
+      confidence:      { type: float }
+      is_duplicate_of: { type: string }
+      is_stale:        { type: boolean }
+  edges:
+    type: list
+    description: Relationships between memory nodes
+    items:
+      from:     { type: string }
+      to:       { type: string }
+      relation: { type: enum, values: [related_to, contradicts, supersedes, depends_on, duplicate_of] }
+      weight:   { type: float }
+  build_history:
+    type: list
+    description: Rolling log of graph builds (last 20)
+    items:
+      built_at:           { type: datetime }
+      node_count:         { type: integer }
+      duplicates_found:   { type: integer }
+      contradictions_found: { type: integer }
+      stale_found:        { type: integer }
+      digest_tokens:      { type: integer }

skills/openclaw-native/memory-graph-builder/example-state.yaml

@@ -0,0 +1,43 @@
+# Example runtime state for memory-graph-builder
+last_build_at: "2026-03-15T22:00:12.000000"
+node_count: 48
+edge_count: 15
+duplicate_count: 4
+contradiction_count: 1
+stale_count: 3
+digest_tokens: 420
+build_history:
+  - built_at: "2026-03-15T22:00:12.000000"
+    node_count: 48
+    duplicates_found: 4
+    contradictions_found: 1
+    stale_found: 3
+    digest_tokens: 420
+# ── Walkthrough ──────────────────────────────────────────────────────────────
+# Nightly cron runs:  python3 graph.py --build
+#
+#   Memory Graph Builder — 2026-03-15 22:00
+#   ────────────────────────────────────────────────────────────────
+#     Memory lines   : 52
+#     Nodes          : 48
+#     Edges          : 15
+#     Duplicates     : 4
+#     Contradictions : 1
+#     Stale          : 3
+#     Digest tokens  : ~420
+#
+#     Digest written to: ~/.openclaw/workspace/memory-digest.md
+#
+# python3 graph.py --duplicates
+#   DUP:  "User prefers dark mode for all applications"
+#   ORIG: "User likes dark theme everywhere"
+#
+# python3 graph.py --contradictions
+#   A: "User uses Python 3.8 for backend services"
+#   B: "User recently upgraded to Python 3.12"
+#   → Resolve by editing MEMORY.md
+#
+# python3 graph.py --prune --dry-run
+#   Dry run — would prune 7 entries:
+#     [duplicate] "User prefers dark mode for all applications"
+#     [stale] "Working on migration to React 17"