Summary

We propose adding an External Memory Provider API to OpenClaw that enables zero-downtime context compaction by delegating memory management to an external system. This eliminates the current 30-60 second agent blackout during compaction — reducing it to <100ms with zero perceived downtime.

Problem

When an OpenClaw agent's context window fills up, the platform performs synchronous in-band compaction:

1. Agent stops responding
2. Entire context is sent to an LLM for summarization
3. Summary replaces the original context
4. Agent resumes with degraded memory

Impact: 30-60s blackout, information loss, no audit trail, unpredictable timing. For production use cases (customer support, financial services, healthcare) this is a dealbreaker.

Proposed Solution: Hot-Swap Context with External Memory Provider

┌──────────────────────────────────────────┐
│            OpenClaw Agent                │
│  Context Slot A (active) ←→ Slot B      │
│         ↕                    ↕           │
│  ┌────────────────────────────────┐      │
│  │   Memory Provider Interface    │      │
│  └──────────┬─────────────────────┘      │
└─────────────┼────────────────────────────┘
              ▼
┌─────────────────────────────┐
│  External Memory Provider   │
│  • Continuous async sync    │
│  • Background compression   │
│  • Pre-built context ready  │
│  • Full audit trail         │
└─────────────────────────────┘

How It Works

1. Continuous Sync — Every message written to memory provider async (fire-and-forget, local socket, ~1ms)
2. Background Compression — Provider maintains compressed context summary, updated asynchronously (cheap local model)
3. Atomic Swap — At capacity, OpenClaw reads pre-built context from provider (~50ms), swaps in inter-message gap
4. On-Demand Recall — Agent queries provider for older details via tool call (~10-50ms)

Proposed API

interface MemoryProvider {
  // Fire-and-forget after each message (async, not in critical path)
  onMessage(sessionId: string, message: Message): Promise<void>;
  
  // Returns pre-built compressed context (maxChars as model-agnostic approx)
  getCompressedContext(sessionId: string, maxChars: number): Promise<CompressedContext>;
  
  // On-demand recall tool
  recall(sessionId: string, query: string, limit?: number): Promise<MemoryEntry[]>;
  
  ping(): Promise<{ ok: boolean; latencyMs: number }>;
}

Lifecycle Hooks

interface SessionHooks {
  'pre-compaction': (session: Session) => Promise<void>;
  'post-compaction': (session: Session, newContext: CompressedContext) => Promise<void>;
  'session-start': (session: Session) => Promise<CompressedContext | null>;  // Cold-start recovery
  'session-end': (session: Session) => Promise<void>;
}

Configuration

{
  "memory": {
    "provider": "uaml",       // or "builtin" (default, backward compatible)
    "endpoint": "http://localhost:8770",
    "compaction": {
      "strategy": "hot-swap", // "hot-swap" | "builtin"
      "threshold": 0.85,
      "targetSize": 0.40
    }
  }
}

Performance Comparison

Edge Cases & Error Handling

• Message during swap: Swap occurs in inter-message gap; incoming messages queued during ~100ms swap
• Provider failure: Fallback to builtin compaction (graceful degradation, never block agent)
• Cold start: session-start hook enables context reconstruction from historical data

Security

• Memory provider runs locally by default (localhost/Unix socket)
• Remote providers require TLS + auth token
• Provider must respect session/agent data isolation

Backward Compatibility

• Default behavior unchanged — builtin compaction remains default
• Memory provider is opt-in via configuration
• Existing sessions unaffected

Reference Implementation

We have a working memory system (UAML Memory) that provides sub-100ms local recall, temporal reasoning, provenance tracking, and MCP compatibility. We're ready to build the OpenClaw adapter once the Provider API is defined.

GitHub: github.com/uaml-memory/uaml

Proposed Phased Roadmap

Phase 1 alone would already enable external memory integration and demonstrate value.

We're happy to contribute to the implementation. This could transform OpenClaw from a powerful hobby tool into an enterprise-grade agent platform.