surrealdb-memory

What this skill does

# SurrealDB Knowledge Graph Memory v2.2

A comprehensive knowledge graph memory system with semantic search, episodic memory, working memory, automatic context injection, and **per-agent isolation** — enabling every agent to become a continuously self-improving AI.

## Description

Use this skill for:
- **Semantic Memory** — Store and retrieve facts with confidence-weighted vector search
- **Episodic Memory** — Record task histories and learn from past experiences
- **Working Memory** — Track active task state with crash recovery
- **Auto-Injection** — Automatically inject relevant context into agent prompts
- **Outcome Calibration** — Facts gain/lose confidence based on task outcomes
- **Self-Improvement** — Scheduled extraction and relation discovery make every agent smarter over time

**Triggers:** "remember this", "store fact", "what do you know about", "memory search", "find similar tasks", "learn from history"

> **Security:** This skill reads workspace memory files and sends their content to OpenAI for extraction. It registers two background cron jobs and (optionally) patches OpenClaw source files. All behaviors are opt-in or documented. See [SECURITY.md](SECURITY.md) for the full breakdown before enabling.
>
> **Required:** `OPENAI_API_KEY`, `surreal` binary, `python3` ≥3.10

---

## 🔄 Self-Improving Agent Loop

This is the core concept: **every agent equipped with this skill improves itself automatically**, with no manual intervention required. Two scheduled cron jobs — knowledge extraction and relationship correlation — run on a fixed schedule and continuously grow the knowledge graph. Combined with auto-injection, the agent gets progressively smarter with each conversation.

### The Cycle

```
[Agent Conversation]
       ↓  stores important facts via knowledge_store_sync
[Memory Files]  ← agent writes to MEMORY.md / daily memory/*.md files
       ↓  every 6 hours — extraction cron fires
[Entity + Fact Extraction]  ← LLM reads files, extracts structured facts + entities
       ↓  facts stored with embeddings + agent_id tag
[Knowledge Graph]  ← SurrealDB: facts, entities, mentions
       ↓  daily at 3 AM — relation discovery cron fires
[Relationship Correlation]  ← AI finds semantic links between facts
       ↓  relates_to edges created between connected facts
[Richer Knowledge Graph]  ← facts are no longer isolated; they form a web
       ↓  on every new message — auto-injection reads the graph
[Context Window]  ← relevant facts + relations + episodes injected automatically
       ↓
[Better Responses]  ← agent uses accumulated knowledge to respond more accurately
       ↑  new insights written back to memory files → cycle repeats
```

### What Each Scheduled Job Does

#### Job 1 — Knowledge Extraction (every 6 hours)
**Script:** `scripts/extract-knowledge.py extract`

- Reads `MEMORY.md` and all `memory/YYYY-MM-DD.md` files in the workspace
- Uses an LLM (GPT-4) to extract structured facts, entities, and key concepts
- Hashes file content to skip unchanged files — only processes diffs
- Stores each fact with:
  - A vector embedding (OpenAI `text-embedding-3-small`) for semantic search
  - A `confidence` score (defaults to 0.9)
  - An `agent_id` tag so facts stay isolated to the right agent
  - `source` metadata pointing back to the originating file
- Result: raw conversational knowledge becomes searchable, structured memory

#### Job 2 — Relationship Correlation (daily at 3 AM)
**Script:** `scripts/extract-knowledge.py discover-relations`

- Queries the graph for facts that have no relationships yet ("isolated facts")
- Batches them and asks an LLM to identify semantic connections between them
- Creates `relates_to` edges in SurrealDB linking related facts
- Result: isolated facts become a **connected knowledge web** — the agent can now traverse relationships, not just keyword-match
- Over time, the graph evolves from a flat list into a rich semantic network

#### Job 3 — Deduplication (daily at 4 AM)
**Script:** `scripts/extract-knowledge.py dedupe --threshold 0.92`

- Compares all facts using vector similarity (cosine distance)
- Facts above the threshold (92% similar) are flagged as duplicates
- Keeps the higher-confidence fact, removes the duplicate
- Prevents extraction from creating bloat over time
- Result: a clean, non-redundant knowledge base

#### Job 4 — Reconciliation (weekly, Sundays at 5 AM)
**Script:** `scripts/extract-knowledge.py reconcile --verbose`

- Applies time-based confidence decay to aging facts
- Prunes facts that have decayed below minimum confidence
- Cleans orphaned entities with no linked facts
- Consolidates near-duplicate entities
- Result: the knowledge graph stays healthy, relevant, and pruned of stale information

### Why This Makes Agents Self-Improving

When auto-injection is enabled, every new conversation starts with the most relevant slice of the accumulated knowledge graph. As the agent:
1. Has conversations → writes insights to memory files
2. Extraction job fires → converts those insights into structured facts
3. Relation job fires → connects those facts to existing knowledge
4. Next conversation → auto-injection pulls in richer, more connected context

...the agent effectively gets smarter with every cycle. It learns from its own outputs, grounds future responses in its accumulated history, and avoids repeating mistakes (via episodic memory and outcome calibration).

### OpenClaw Cron Jobs (Required)

The skill requires **5 cron jobs** for full self-improving operation. All run as isolated background sessions with no delivery:

| Job Name | Schedule | What it runs |
|----------|----------|--------------|
| Memory Knowledge Extraction | Every 6 hours (`0 */6 * * *`) | `extract-knowledge.py extract` — extracts facts from memory files |
| Memory Relation Discovery | Daily at 3 AM (`0 3 * * *`) | `extract-knowledge.py discover-relations` — AI-powered relationship finding |
| Memory Deduplication | Daily at 4 AM (`0 4 * * *`) | `extract-knowledge.py dedupe --threshold 0.92` — removes duplicate/near-duplicate facts |
| Memory Reconciliation | Weekly Sun 5 AM (`0 5 * * 0`) | `extract-knowledge.py reconcile --verbose` — prunes stale facts, applies confidence decay, cleans orphans |

> All jobs use `sessionTarget: "isolated"` with `delivery: none`. They run in fully isolated background sessions and **never fire into the main agent session**. A bottom-right corner toast notification appears in the Control UI when each job starts and completes.

**Setup commands** (run after installation):

```bash
# 1. Knowledge Extraction — every 6 hours
openclaw cron add \
  --name "Memory Knowledge Extraction" \
  --cron "0 */6 * * *" \
  --agent main --session isolated --no-deliver \
  --timeout-seconds 300 \
  --message "Run memory knowledge extraction. Execute: cd SKILL_DIR && source .venv/bin/activate && python3 scripts/extract-knowledge.py extract"

# 2. Relation Discovery — daily at 3 AM
openclaw cron add \
  --name "Memory Relation Discovery" \
  --cron "0 3 * * *" --exact \
  --agent main --session isolated --no-deliver \
  --timeout-seconds 300 \
  --message "Run memory relation discovery. Execute: cd SKILL_DIR && source .venv/bin/activate && python3 scripts/extract-knowledge.py discover-relations"

# 3. Deduplication — daily at 4 AM
openclaw cron add \
  --name "Memory Deduplication" \
  --cron "0 4 * * *" --exact \
  --agent main --session isolated --no-deliver \
  --timeout-seconds 120 \
  --message "Run knowledge graph deduplication. Execute: cd SKILL_DIR && source .venv/bin/activate && python3 scripts/extract-knowledge.py dedupe --threshold 0.92"

# 4. Reconciliation — weekly on Sundays at 5 AM
openclaw cron add \
  --name "Memory Reconciliation" \
  --cron "0 5 * * 0" --exact \
  --agent main --session isolated --no-deliver \
  --timeout-seconds 180 \
  --message "Run knowledge graph reconciliation. Execute: cd SKILL_DIR && source .venv/bin/activate && python3 scripts/extract-knowledge.py reconcile --v