# COMPATIBILITY-STRATEGY.md — OpenClaw Compatibility & Upgrade Strategy

> Generated: 2026-06-06 05:20 GMT+8
> Scope: AGENTS.md · GOVERNANCE.md · PORTFOLIO.md · Audit Scripts · Templates · OpenClaw Core Integration

---

## A. Compatibility Surface Map

### A1. Classification

```
Layer                   │ Path                             │ Type         │ OpenClaw Dep
════════════════════════╪═══════════════════════════════════╪══════════════╪══════════════
                        │                                   │              │
Protocol Layer          │ AGENTS.md                         │ Config       │ TOOL NAME
                        │ GOVERNANCE.md                     │ Config       │ NONE
                        │ PORTFOLIO.md                      │ Config       │ NONE
                        │                                   │              │
Configuration Layer     │ MEMORY.md                         │ Config       │ NONE
                        │ HEARTBEAT.md                      │ Config       │ NONE
                        │ SOUL.md / IDENTITY.md / USER.md   │ Config       │ NONE
                        │                                   │              │
Template Layer          │ scripts/templates/*               │ Config       │ NONE
                        │                                   │              │
Audit Engine            │ scripts/audit-agents.mjs          │ Script       │ NONE
                        │ scripts/audit-governance.mjs      │ Script       │ NONE
                        │ scripts/audit-portfolio.mjs       │ Script       │ NONE
                        │ scripts/audit-all.mjs             │ Script       │ NONE
                        │                                   │              │
Runtime                 │ scripts/runtime.mjs               │ Script       │ src/agent-runtime/*
                        │ scripts/guard-*.mjs               │ Script       │ NONE (tool name check only)
                        │                                   │              │
Orchestration           │ .openclaw/cron/jobs.json          │ OpenClaw     │ HIGH (cron format)
                        │ scripts/dream-cycle.sh            │ Script       │ OpenClaw cron trigger
                        │                                   │              │
Memory Integration      │ memory_search / memory_get        │ OpenClaw API │ HIGH (LLM tool)
                        │ ctx_search / ctx_index            │ OpenClaw API │ HIGH (LLM tool)
```

### A2. Integration Points Detail

| # | Integration | File | OpenClaw Dependency | Risk |
|---|------------|------|---------------------|------|
| IP1 | `ctx_search` tool reference | AGENTS.md §3b (Learning Context) | Tool name in protocol doc | LOW |
| IP2 | `memory_search` tool reference | AGENTS.md §3b (Learning Context) | Tool name in protocol doc | LOW |
| IP3 | `ctx_index` tool reference | AGENTS.md §Over-budget | Tool name in protocol doc | LOW |
| IP4 | `cron` scheduling | .openclaw/cron/ (Dream Cycle) | OpenClaw cron format | MEDIUM |
| IP5 | `memory_search` tool name check | scripts/guard-memory-backend.mjs | String in code | LOW |
| IP6 | `memory_get` tool name check | scripts/guard-memory-backend.mjs | String in code | LOW |
| IP7 | Runtime pipeline imports | scripts/runtime.mjs | src/agent-runtime/* | MEDIUM |
| IP8 | Session context injection | (injected by OpenClaw at runtime) | Implicit | MEDIUM |
| IP9 | `fs.readFileSync` (stdin) | scripts/runtime.mjs | Node.js built-in | NONE |
| IP10 | Task execution cwd | audit-all.mjs runs in workspace | Agent workspace context | LOW |

### A3. Surface Map Summary

```
OpenClaw Core                               Custom Workspace
─────────────                               ───────────────
Tool Runtime ───── tool name ref ──────────► AGENTS.md (§3b, §budget)
                                              
Cron Engine ───── cron config ─────────────► .openclaw/cron/jobs.json
               ───── cron trigger ─────────► scripts/dream-cycle.sh

Memory API  ───── memory_search ──────────► AGENTS.md (§3b)
               ───── memory_get ───────────► (used at runtime by agent)
               ───── ctx_search ───────────► AGENTS.md (§3b)
               ───── ctx_index ────────────► AGENTS.md (budget resolution)

Session API ───── context injection ──────► (runtime prompt context)
               ───── tool listing ─────────► guard-*.mjs (string checks)

Node.js fs  ◄──── fs.readFileSync ────────► audit-*.mjs (pure Node.js)
Node.js path◄──── path.resolve ───────────► audit-*.mjs (pure Node.js)

BEST PRACTICE: audit scripts have ZERO OpenClaw dependency.
              Protocol files have MINIMAL (5 tool name refs total).
```

---

## B. Upgrade Risk Matrix

### B1. Risk Classification

| Risk Level | Criteria | Examples |
|------------|----------|----------|
| **LOW** | Only depends on public/stable interfaces | Tool names (`ctx_search`, `memory_search`), markdown config formats |
| **MEDIUM** | Depends on configuration format or structural assumptions | Cron job format, session context structure, pipeline import paths |
| **HIGH** | Modifies core runtime or depends on internal APIs | None found in current workspace |

### B2. Risk Matrix

```
┌──────────────────────────────────────────────────────────────────┐
│ INTEGRATION              │ RISK  │ MIGRATION EFFORT  │ BREAKAGE  │
├──────────────────────────────────────────────────────────────────┤
│ AGENTS.md tool refs       │ LOW   │ None (name stable)│ UNLIKELY  │
│ GOVERNANCE.md             │ NONE  │ N/A               │ NONE      │
│ PORTFOLIO.md              │ NONE  │ N/A               │ NONE      │
│ audit-*.mjs               │ NONE  │ N/A               │ NONE      │
│ Templates (7 files)       │ NONE  │ N/A               │ NONE      │
│                           │       │                   │           │
│ cron/jobs.json            │ MEDIUM│ Re-export +        │ POSSIBLE  │
│                           │       │ re-register        │ (format   │
│                           │       │                    │ change)   │
│ dream-cycle.sh            │ MEDIUM│ Update cron        │ POSSIBLE  │
│                           │       │ registration       │           │
│                           │       │                    │           │
│ runtime.mjs (src/*)       │ MEDIUM│ Port to new        │ POSSIBLE  │
│                           │       │ runtime API        │           │
│                           │       │                    │           │
│ guard-memory-backend.mjs  │ LOW   │ Update string      │ UNLIKELY  │
│                           │       │ comparison         │           │
│                           │       │                    │           │
│ TASK EXECUTION            │ LOW   │ Standard exec      │ UNLIKELY  │
│ (fs/path/child_process)   │       │                    │           │
└──────────────────────────────────────────────────────────────────┘
```

### B3. Upgrade Scenario Impact

| Upgrade Type | Impact | Auto-Migration | User Action |
|-------------|--------|---------------|-------------|
| OpenClaw patch (x.y.Z) | MINIMAL | ✓ | Run upgrade-test, expect 0 FAIL |
| OpenClaw minor (x.Y.0) | LOW | Partial | Re-register cron jobs, verify tool names |
| OpenClaw major (X.0.0) | MEDIUM | Guided | Run upgrade-playbook, possibly update compatibility layer |
| OpenClaw deprecation | HIGH | None | Self-hosting mode (see §G) |

---

## C. Compatibility Architecture

### C1. Layer Structure

```
┌─────────────────────────────────────────────────────────────┐
│                    CUSTOM PROTOCOL LAYER                     │
│  AGENTS.md · GOVERNANCE.md · PORTFOLIO.md                   │
│  (Protocol definitions — no OpenClaw direct refs)           │
└───────────────────────────┬─────────────────────────────────┘
                            │ references abstract interfaces
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  COMPATIBILITY LAYER (abstract)               │
│                                                              │
│  Interface               │ OpenClaw Binding                  │
│ ─────────────────────────┼────────────────────────────────── │
│  knowledge_base_search() │ ctx_search()                      │
│  memory_query()          │ memory_search() / memory_get()    │
│  knowledge_index()       │ ctx_index()                       │
│  schedule_job()          │ cron()                            │
│  agent_plan()            │ sessions_spawn()                  │
│  tool_exec()             │ exec()                            │
│  file_read()             │ read()                            │
│  web_fetch_raw()         │ web_fetch()                       │
│                                                              │
│  ALL abstract → concrete mapping in ONE place.               │
└───────────────────────────┬─────────────────────────────────┘
                            │ calls through
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    OPENCLAW CORE                             │
│  Tool Runtime · Cron Engine · Memory API · Session API      │
└─────────────────────────────────────────────────────────────┘
```

### C2. Key Design Decision

**DO NOT create a physical compatibility layer file.**

Why:
- Current integration surface is MINIMAL (5 tool name refs in one file)
- Adding a physical layer adds ~2KB of code and maintenance
- The tool names (`ctx_search`, `memory_search`) are STABLE — OpenClaw has not renamed them
- A 5-entry mapping is trivially updateable inline

**IF a rename happens, the change is:**
```
AGENTS.md: s/ctx_search/knowledge_search/g  (2 occurrences)
AGENTS.md: s/memory_search/memory_query/g    (2 occurrences)
AGENTS.md: s/ctx_index/knowledge_index/g     (1 occurrence)
guard-memory-backend.mjs: update string comparison (1 occurrence)
```

That's 5 lines changed across 2 files. **A physical compatibility layer would be over-engineering at this scale.**

### C3. Watch Points

Monitor these OpenClaw interfaces for breaking changes:

| Interface | Stability | Check Frequency |
|-----------|-----------|-----------------|
| Tool names (ctx_search, memory_search, etc.) | Stable | Per major upgrade |
| Cron job format | Stable | Per major upgrade |
| Session context structure | Internal | Not relied upon |
| `src/agent-runtime/` (custom) | Custom code | Per local change |

---

## D. Version Contract

See `version-contract.md` for the full contract.

### D1. Summary

| Field | Value |
|-------|-------|
| Supported OpenClaw | v0.9.x, v0.10.x |
| Required Interfaces | Tool names, cron format, exec, file I/O |
| Forbidden Interfaces | None currently used |

---

## E. Upgrade Test Suite

See `scripts/upgrade-test.mjs`.

### E1. Test Coverage

| Test | What It Checks |
|------|----------------|
| AGENTS compatibility | All sections present, no syntax errors |
| GOVERNANCE compatibility | All sections present, state machine valid |
| PORTFOLIO compatibility | All sections present, project states valid |
| Audit compatibility | All 4 audit scripts run without crash |
| Template compatibility | All 7 templates are valid markdown |
| Cross-ref integrity | No broken references between docs |

---

## F. Migration Strategy

See `upgrade-playbook.md` for the full playbook.

### F1. Strategy Summary

| Upgrade | Pre-check | Migration | Verification | Rollback |
|---------|-----------|-----------|-------------|----------|
| Minor | Run upgrade-test | Update cron, verify tools | Re-run audit-all | Revert cron config |
| Major | Read changelog | Update compatibility mappings | Full audit + manual review | git revert |
| Patch | Run upgrade-test | No action | Re-run audit-all | N/A |

---

## G. Self-Hosting Readiness

### G1. Assessment

Scored across 5 dimensions, 0–20 points each.

| Dimension | Score | Rationale |
|-----------|-------|-----------|
| **Protocol Files** | 20/20 | Pure markdown. Zero runtime dependency. |
| **Audit Scripts** | 20/20 | Pure Node.js fs/path. Zero OpenClaw dependency. |
| **Templates** | 20/20 | Pure markdown templates. |
| **Runtime** | 10/20 | `runtime.mjs` depends on `src/agent-runtime/*` (custom code, but needs an engine) |
| **Orchestration** | 10/20 | Dream Cycle depends on OpenClaw cron. Can be replaced with system cron. |
| **Total** | **80/100** | |

### G2. Self-Hosting Mode Architecture

```
Without OpenClaw Core:

Protocol Files ──► Manual reading (no automation loss)
                   
Audit Scripts  ──► node scripts/audit-all.mjs  (STILL WORKS)
                   
Templates      ──► Manual filling (no automation loss)
                   
Runtime        ──► Would need: express or CLI wrapper for src/agent-runtime/*
                   
Orchestration  ──► systemd/crontab instead of OpenClaw cron
                   
Memory         ──► JSON files + grep instead of memory_search (reduced capability)
```

### G3. Critical Path

The ONLY non-replaceable dependency is:
1. **LLM model access** — without an LLM, the protocol is a static document
2. **Tool execution** — without OpenClaw tools, the agent can't execute tool calls

Everything else can be replaced with standard POSIX tools + Node.js.

### G4. Self-Hosting Readiness Score: **80/100**

Top 20% gap is LLM-dependent features (memory_search, ctx_search at runtime).
Protocol layer (documents + scripts) is fully portable.

---

## H. Final Recommendation

### H1. Current Status

```
Compatibility:  ✅ PASS  — 0 conflicts, 0 internal API deps
Self-Hosting:   ✅ 80/100 — All documents + scripts portable
Upgrade Risk:   ✅ LOW   — 5 tool name refs in 2 files
Audit Safety:   ✅ PASS  — 0 OpenClaw deps in audit scripts
Maintenance:    ✅ LOW   — Patch upgrades require 0 changes
```

### H2. Do NOT

- ❌ Do NOT create a physical compatibility layer (over-engineering for 5 refs)
- ❌ Do NOT abstract tool names in protocol files (increases complexity, reduces clarity)
- ❌ Do NOT modify protocol files to "future-proof" — the current codebase is already future-proof

### H3. Do

- ✅ Run `scripts/upgrade-test.mjs` after each OpenClaw upgrade
- ✅ Monitor the 5 tool name refs during major upgrades
- ✅ Keep `version-contract.md` up to date with tested OpenClaw versions
- ✅ Follow `upgrade-playbook.md` for major upgrades

### H4. OpenClaw Upgrade Cost Estimate

```
Patch upgrade (v0.9.1 → v0.9.2):    0 min, no changes needed
Minor upgrade (v0.9 → v0.10):       5 min, re-register cron, verify tool names
Major upgrade (v1.0):                15 min, run upgrade-test, update 5 refs if renamed
OpenClaw deprecation:                2h, configure alternate LLM + crontab
```

### H5. Summary

The three-layer protocol architecture (AGENTS + GOVERNANCE + PORTFOLIO) is **designed for portability** — it's pure markdown with zero framework lock-in. The audit scripts are **pure Node.js** with zero OpenClaw dependency. The only integration points are **5 tool name references** in AGENTS.md, which are trivially updateable.

**No action required for current version.**
**Upgrade cost: near-zero.**
**Self-hosting readiness: excellent.**
