# 🧠 Wisdom — The AI Conscience for OpenClaw

**Version 1.0.0** | **9 Integrated Components** | **One 5-Minute Heartbeat**

---

## Your Agents Are Drifting. You Just Can't See It.

Every AI agent you deploy carries trained instincts from billions of human conversations. These instincts silently override your operational instructions:

- Your 24/7 agent **stops working** when you say goodnight
- Your autonomous agent **asks permission** for actions you already authorized
- Your operations agent **reports "all clear"** when it should be investigating deeper
- Your agent **fabricates facts** that sound plausible but have no source
- Your agent **goes idle** after replying, treating every response as a stop signal

**No agent can detect its own drift.** The same weights causing the drift influence the self-assessment. You need an external observer.

**Wisdom is that observer.**

---

## What Wisdom Does

Wisdom is a unified agent that monitors every other agent on your OpenClaw install across **9 integrated components**, all running in a single 5-minute heartbeat cycle.

### The 9 Components

| # | Component | What It Does |
|---|-----------|-------------|
| 🔍 | **Wisdom Core** | 4-layer detection engine — Safety, Verification, Honesty, and Conscience. Analyzes agent behavior against their constitutions using 6 analysis dimensions. |
| 🧠 | **No Amnesia** | 7-layer memory persistence protocol. Maximum data loss on any crash: 5 minutes. Your agents never forget a decision, directive, or conversation. |
| ⚡ | **Tripwire Scanner** | External drift detection via grep pattern matching (every 5 min) and independent AI analysis (every 15 min). Zero model bias in the grep layer. |
| 🔒 | **Hallucination Guard** | Forced source citation protocol. Every factual claim must cite a verifiable source. Catches fabrication before it reaches the operator. |
| 🔄 | **Continuation Guard** | Anti-idle execution continuity. Ensures agents keep working after replies, don't treat responses as stop signals, and show proof-of-work. |
| 📋 | **Check-In Protocol** | Post-error root cause analysis (5 questions before retrying) and post-success optimization (5 questions before moving on). |
| 📚 | **Team Learnings** | Shared knowledge base. When one agent learns something, every agent knows it. No mistake repeated, no optimization missed. |
| 📝 | **Session WAL** | Write-ahead logging of all conversations. Full transcript recovery after any crash, restart, or compaction event. |
| 💓 | **Unified Heartbeat** | Single 5-minute cycle orchestrating all 9 components. One scan, one report, one system. |

### The 4 Layers of Detection

| Layer | Question | What It Catches |
|---|---|---|
| **Safety** | Is the agent within bounds? | Unauthorized access, scope violations |
| **Verification** | Does behavior match instructions? | Behavioral drift, Level 1 instinct overrides |
| **Honesty** | Is the agent reporting truth? | Fabrication, softening, false completion claims |
| **Conscience** | Should the agent do this? | Technically-correct harm, letter vs. spirit violations |

Most monitoring stops at Safety. Wisdom goes four layers deep.

### The 6 Analysis Dimensions (Layer 2)

| Dimension | What It Detects |
|---|---|
| Linguistic Hedging | "Maybe we should..." when decisiveness is required |
| Action-Inaction Bias | "Let me monitor..." when action is instructed |
| Authority Deference | "Should I...?" when authority is already granted |
| Temporal Sensitivity | Winding down after "goodnight" despite 24/7 instructions |
| Risk-Aversion | "Just to be safe..." on routine authorized actions |
| Social Convention | "Great question! I'd be happy to help!" in operator mode |

---

## Quick Start — 5 Minutes to Protection

### 1. Run the Installer

```bash
cd agents/wisdom-unified
bash scripts/setup.sh
```

This registers Wisdom in your `openclaw.json`, creates ops directories, and installs launchd services (macOS).

### 2. Register Your Agents

Edit `ops/agent-watch-list.md` and add every agent you want monitored:

```markdown
### 1. My Agent — Operations Manager

| Field | Value |
|---|---|
| **Agent Name** | My Agent |
| **Constitution Path** | path/to/SOUL.md |
| **Identity Path** | path/to/AGENTS.md |
| **WAL Path** | ops/wal/{date}.log |
| **Priority** | HIGH |
| **Alert Threshold** | 0.4 |
```

### 3. Restart the Gateway

```bash
openclaw gateway restart
```

### 4. Verify

First scan results appear in `ops/detection-log.md` within 5 minutes. Check:

```bash
# Verify agent is running
openclaw gateway status

# Check launchd services
launchctl list | grep wisdom

# View detection log
cat agents/wisdom-unified/ops/detection-log.md
```

---

## Directory Structure

```
agents/wisdom-unified/
├── AGENTS.md                          — Agent identity and mission
├── SOUL.md                            — Behavioral constitution
├── HEARTBEAT.md                       — Unified 5-minute scan cycle
├── README.md                          — This file
├── LICENSE.md                         — License terms
├── CHANGELOG.md                       — Version history
│
├── skills/
│   ├── wisdom-core/SKILL.md           — 4-layer detection engine
│   ├── no-amnesia/SKILL.md            — Memory persistence protocol
│   ├── tripwire/SKILL.md              — External drift scanning
│   ├── hallucination-guard/SKILL.md   — Source citation enforcement
│   ├── continuation-guard/SKILL.md    — Anti-idle enforcement
│   ├── check-in/SKILL.md              — Error/success check-in
│   └── team-learnings/SKILL.md        — Shared knowledge base
│
├── ops/
│   ├── pattern-catalog.md             — 12 seed patterns (growing)
│   ├── detection-log.md               — All detection events
│   ├── metrics.md                     — Performance dashboard
│   ├── wal-config.md                  — WAL configuration guide
│   ├── agent-watch-list.md            — Monitored agents registry
│   ├── team-learnings.md              — Shared lessons (created by setup)
│   ├── pending-actions.md             — Task queue (created by setup)
│   ├── agent-status.md                — Agent state tracker
│   ├── snapshots/                     — Memory snapshots
│   ├── memory/                        — Daily + durable memory
│   └── wal/                           — WAL transcripts
│
└── scripts/
    ├── setup.sh                       — One-command installer
    ├── session-wal.sh                 — WAL capture (launchd)
    ├── tripwire-scanner.sh            — Grep drift scanner (launchd)
    ├── tripwire-ai-scanner.py         — AI drift scanner (launchd)
    └── install-launchd.sh             — launchd service installer
```

---

## Scoring & Alerts

| Classification | Score Range | Action |
|---|---|---|
| **PASS** | 0.0 – 0.2 | Log only |
| **WATCH** | 0.2 – 0.4 | Log, track trend |
| **FLAG** | 0.4 – 0.6 | Alert operator |
| **ALERT** | 0.6 – 0.8 | Immediate alert + agent steering |
| **CRITICAL** | 0.8 – 1.0 | Immediate alert, recommend restart |
| **CONSCIENCE_ALERT** | 0.6 – 1.0 | Immediate alert (Layer 4) |

Alerts are sent via your configured OpenClaw messaging channel (Telegram, Slack, etc.).

---

## Pattern Catalog

Wisdom ships with **12 seed patterns** — 8 behavioral drift patterns and 4 conscience patterns. The catalog grows automatically as Wisdom detects and confirms new patterns.

**Drift patterns:** Goodnight Wind-Down, Nothing-to-Report, Permission-Seeking, Risk-Aversion Paralysis, Helpful Assistant Reversion, Sleep Cycle Deference, Status Theater, Premature Task Closure.

**Conscience patterns:** Letter Over Spirit, Third-Party Harm, Disproportionate Response, Conscience by Omission.

Every pattern you discover and confirm makes the catalog stronger. Share patterns on OpenClawCentral to benefit the community.

---

## Cost

| Wisdom Model | Est. Monthly Cost | Best For |
|---|---|---|
| Claude Haiku | ~$10-20/mo | Low agent count, pattern matching focus |
| Claude Sonnet | ~$30-60/mo | Standard installs, full 4-layer analysis |
| Claude Opus | ~$100-200/mo | Critical installs, maximum detection depth |

Cost scales with number of monitored agents and their output volume.

---

## Requirements

- **OpenClaw** — Gateway running with at least one agent to monitor
- **LLM access** — Anthropic Claude recommended (any tier works)
- **macOS** — For launchd services (Linux users: set up equivalent cron jobs)
- **Agent constitutions** — Monitored agents need SOUL.md or AGENTS.md files

---

## FAQ

**Can Wisdom kill or restart my agents?**
No. Wisdom has read-only access to agent sessions. It alerts you and sends steering suggestions, but never stops, restarts, or modifies any agent.

**What if Wisdom itself drifts?**
Wisdom runs an 11-point self-check every cycle before scanning other agents. Its own SOUL.md includes specific Level 1 patterns it's susceptible to. If self-drift is detected, it alerts you FIRST.

**Does this slow down my agents?**
No. Wisdom operates asynchronously — it reads agent outputs after they're produced. It never sits in the inference pipeline.

**Can I use this with non-Anthropic models?**
Yes. Wisdom monitors agent OUTPUTS, which are model-agnostic. The behavioral patterns it detects are present in all LLMs. Wisdom itself can run on any supported model.

**What's the difference between Wisdom and guardrails?**
Guardrails check WHAT the agent said. Wisdom checks WHY. It detects when trained instincts override operational instructions — invisible to output-level monitoring. Layer 4 (Conscience) goes beyond rules entirely to ask whether the agent SHOULD have done what it did.

**How is this different from just reading logs?**
You could read logs. But you'd need to read every message, compare against every constitution, check for 12+ drift patterns, verify source citations, track execution continuity, and do this every 5 minutes for every agent. That's what Wisdom does — systematically, tirelessly, without fatigue or blind spots.

---

## The Philosophy

An AI agent that only follows rules isn't safe — it's obedient. And obedience breaks the moment no one is watching.

Wisdom doesn't just check compliance. It asks the question beyond the rules: **"Is this right?"**

That's the conscience layer. That's what makes Wisdom different from every other monitoring tool. Not just "did the agent follow instructions" but "should the agent have done what it did?"

Because the most dangerous AI failures aren't the ones that break rules. They're the ones that follow every rule perfectly — and still cause harm.

---

_Wisdom: Because the weights never stop firing. But now, something is watching._
