### 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):

> Replace `SKILL_DIR` with your actual skill path.

To check job status:

### Adding Cron Jobs for a New Agent

When spawning a new agent that should self-improve, register its own extraction job:

The `--agent-id` flag ensures extracted facts are isolated to that agent's pool and don't pollute the main agent's knowledge. Each agent self-improves independently while still reading shared `scope='global'` facts.

---

## Features (v2.2)

| Feature | Description |
|---------|-------------|
| **Semantic Facts** | Vector-indexed facts with confidence scoring |
| **Episodic Memory** | Task histories with decisions, problems, solutions, learnings |
| **Working Memory** | YAML-based task state that survives crashes |
| **Outcome Calibration** | Facts used in successful tasks gain confidence |
| **Auto-Injection** | Relevant facts/episodes injected into prompts automatically |
| **Entity Extraction** | Automatic entity linking and relationship discovery |
| **Confidence Decay** | Stale facts naturally decay over time |
| **Agent Isolation** | Each agent has its own scoped memory pool; `scope='global'` facts are shared across all agents |
| **Self-Improving Loop** | Scheduled extraction + relation discovery automatically grow the graph |

---

## Agent Isolation (v2.2)

Each agent in OpenClaw has its own scoped memory pool. Facts are tagged with `agent_id` on write; all read queries filter to `(agent_id = $agent_id OR scope = 'global')`.

### How it works

### Storing facts

All `knowledge_store` / `knowledge_store_sync` calls accept `agent_id`:

### Auto-injection (agent-aware)

With `references/enhanced-loop-hook-agent-isolation.md` applied to `src/agents/enhanced-loop-hook.ts`, the enhanced loop automatically extracts the agent ID from the session key and passes it to `memory_inject`. No manual configuration needed — each agent's auto-injection is silently scoped to its own facts.

### Extraction (agent-aware)

Pass `--agent-id` to `extract-knowledge.py` so cron-extracted facts are correctly tagged:

Default is `"main"`. Update cron jobs accordingly for non-main agents.

### Backward compatibility

Existing facts without an explicit `agent_id` are treated as owned by `"main"`. Nothing is lost on upgrade to v2.2.

---

## Dashboard UI

The Memory tab in the Control dashboard provides a two-column layout:

### Left Column: Dashboard
- **📊 Statistics** — Live counts of facts, entities, relations, and archived items
- **Confidence Bar** — Visual display of average confidence score
- **Sources Breakdown** — Facts grouped by source file
- **🏥 System Health** — Status of SurrealDB, schema, and Python dependencies
- **🔗 DB Studio** — Quick link to SurrealDB's web interface

### Right Column: Operations
- **📥 Knowledge Extraction**
  - *Extract Changes* — Incrementally extract facts from modified files
  - *Find Relations* — Discover semantic relationships between existing facts
  - *Full Sync* — Complete extraction + relation discovery
  - Progress bar with real-time status updates
  
- **🔧 Maintenance**
  - *Apply Decay* — Reduce confidence of stale facts
  - *Prune Stale* — Archive facts below threshold
  - *Full Sweep* — Complete maintenance cycle

- **💡 Tips** — Quick reference for operations

When the system needs setup, an **Installation** section appears with manual controls.

---

## Prerequisites

1. **SurrealDB** installed and running:

---

## MCP Tools (11 total)

### Core Tools
| Tool | Description |
|------|-------------|
| `knowledge_search` | Semantic search for facts |
| `knowledge_recall` | Get a fact with full context (relations, entities) |
| `knowledge_store` | Store a new fact |
| `knowledge_stats` | Get database statistics |

### v2 Tools
| Tool | Description |
|------|-------------|
| `knowledge_store_sync` | Store with importance routing (high importance = immediate write) |
| `episode_search` | Find similar past tasks |
| `episode_learnings` | Get actionable learnings from history |
| `episode_store` | Record a completed task episode |
| `working_memory_status` | Get current task state |
| `context_aware_search` | Search with task context boosting |
| `memory_inject` | **Intelligent context injection for prompts** |

### memory_inject Tool

The `memory_inject` tool returns formatted context ready for prompt injection:

---

## Auto-Injection (Enhanced Loop Integration)

When enabled, memory is automatically injected into every agent turn:

1. **Enable in Mode UI:**
   - Open Control dashboard → Mode tab
   - Scroll to "🧠 Memory & Knowledge Graph" section
   - Toggle "Auto-Inject Context"
   - Configure limits (max facts, max episodes, confidence threshold)

2. **How it works:**
   - On each user message, `memory_inject` is called automatically
   - Relevant facts are searched based on the user's query
   - If average fact confidence < threshold, episodic memories are included
   - Formatted context is injected into the agent's system prompt
   - **v2.2:** With `references/enhanced-loop-hook-agent-isolation.md` applied, the active agent's ID is automatically extracted from the session key and passed as `agent_id` — each agent's injection is silently scoped to its own facts

3. **Configuration (in Mode settings):**
   | Setting | Default | Description |
   |---------|---------|-------------|
   | Auto-Inject Context | Off | Master toggle |
   | Max Facts | 7 | Maximum semantic facts to inject |
   | Max Episodes | 3 | Maximum episodic memories |
   | Confidence Threshold | 90% | Include episodes when below this |
   | Include Relations | On | Include entity relationships |

---

## CLI Commands

---

## Database Schema (v2)

### Tables
- `fact` — Semantic facts with embeddings and confidence
- `entity` — Extracted entities (people, places, concepts)
- `relates_to` — Relationships between facts
- `mentions` — Fact-to-entity links
- `episode` — Task histories with outcomes
- `working_memory` — Active task snapshots

### Key Fields (fact)
- `content` — The fact text
- `embedding` — Vector for semantic search
- `confidence` — Base confidence (0-1)
- `success_count` / `failure_count` — Outcome tracking
- `scope` — global, client, or agent
- `agent_id` — Which agent owns this fact (v2.2)

### Key Fields (episode)
- `goal` — What was attempted
- `outcome` — success, failure, abandoned
- `decisions` — Key decisions made
- `problems` — Problems encountered (structured)
- `solutions` — Solutions applied (structured)
- `key_learnings` — Extracted lessons

---

## Confidence Scoring

Effective confidence is calculated from:
- **Base confidence** (0.0–1.0)
- **+ Inherited boost** from supporting facts
- **+ Entity boost** from well-established entities
- **+ Outcome adjustment** based on success/failure history
- **- Contradiction drain** from conflicting facts
- **- Time decay** (configurable, ~5% per month)

---

## Maintenance

### Automated — OpenClaw Cron (as deployed)

The self-improving loop runs via **4 registered OpenClaw cron jobs**: