CogOS OpenClaw Plugin

Foveated context engine for OpenClaw — iris-driven variable-resolution context injection from a CogOS kernel.

What it does

This plugin connects OpenClaw to a running CogOS kernel and injects workspace context into every agent turn using foveated rendering — a variable-resolution strategy inspired by how the eye works:

• Foveal center (WHERE): CogOS extracts an anchor and goal from the user's prompt to determine what the agent is focused on.
• Iris width (HOW MUCH): The plugin tracks context window pressure (tokens used vs. available) and sends iris signals to the kernel. Early in a conversation the iris is wide (generous context at full resolution); as the window fills, the iris narrows and only the most salient context survives.

The result: agents get the right context at the right resolution, automatically adapting as conversations grow.

Plugins

cogos/ — Foveated Context Engine

The main plugin. Registers:

Component	Description
Provider	CogOS as an OpenAI-compatible model provider (cogos / cog)
Tools	cogos_memory_search, cogos_memory_read, cogos_coherence_check
Hooks	before_agent_start (iris-driven context injection), before_compaction, after_compaction, agent_end
Service	Kernel health monitoring on startup/shutdown
Command	/iris — show current context window pressure state

cogbus/ — Event Bus Bridge

Routes CogOS bus events (tool invocations, agent lifecycle, system events) to a Discord #events channel via SSE streaming. Includes:

• Cursor-based consumption with server-side ACK tracking (ADR-061)
• Automatic reconnection with exponential backoff
• Glob-style event type filtering
• Session-bound event exclusion (chat messages stay in their session)

Installation

Clone into your OpenClaw extensions directory:

cd /path/to/openclaw/extensions/
git clone https://github.com/cogos-dev/openclaw-plugin.git

# Or symlink individual plugins
ln -s /path/to/openclaw-plugin/cogos ./cogos
ln -s /path/to/openclaw-plugin/cogbus ./cogbus

Install dependencies for each plugin:

cd cogos && npm install
cd ../cogbus && npm install

Configuration

CogOS Plugin

Configure via openclaw.plugin.json or gateway config:

Property	Type	Default	Description
enabled	boolean	true	Enable/disable the plugin
kernelUrl	string	http://localhost:6931	CogOS kernel HTTP endpoint
taaProfile	string	"openclaw"	TAA (Tiered Attentional Assembly) profile for context construction
defaultContextWindow	number	200000	Fallback context window size if the model doesn't specify
tokensPerMessageEstimate	number	250	Estimated tokens per message for iris tracking

CogBus Plugin

Configure in the gateway's channels.cogbus section:

Property	Type	Default	Description
enabled	boolean	true	Enable/disable the event router
busEndpoint	string	http://localhost:6931	CogOS kernel SSE endpoint
busId	string	—	Bus ID to subscribe to
eventsChannel	string	—	Discord channel ID for event dispatch
consumerIdentity	string	"openclaw@cogbus"	Stable consumer identity for cursor tracking
eventTypes	string[]	["system.*", "agent.event.*", ...]	Glob patterns for event types to route

Kernel API Contract

The plugin communicates with the CogOS kernel over HTTP. This is the complete interface between the two systems.

Endpoints Called

Method	Endpoint	Purpose	Timeout
GET	/health	Liveness check, version, uptime	2s
GET	/v1/card	Kernel capabilities, available models, context limits	5s
POST	/v1/context/foveated	Core endpoint — request foveated context assembly	10s
GET	/v1/debug/context	Current attentional field state	10s
GET	/v1/debug/last	Last request's full debug snapshot	10s
GET	/memory/search?query=...&limit=N	Search workspace memory	5s
GET	/memory/read?path=...	Read a specific memory document	5s
GET	/coherence/check	Workspace drift detection	5s

Foveated Context Request → Response (the core loop)

Request — POST /v1/context/foveated:

{
  "prompt": "the user's message text",
  "iris": {
    "size": 200000,    // total context window capacity (tokens)
    "used": 45000      // tokens currently consumed
  },
  "profile": "openclaw",       // TAA profile name
  "session_id": "abc123",      // optional: session continuity
  "user_id": "agent-discord"   // optional: cross-surface identity
}

Response:

{
  "context": "<!-- rendered context string injected before the prompt -->",
  "tokens": 3200,              // tokens in the rendered context
  "anchor": "deployment",      // extracted foveal center (what the user is focused on)
  "goal": "deploy to staging", // extracted goal
  "coherence_score": 0.95,     // workspace coherence at render time
  "tier_breakdown": {
    "tier1": 800,              // nucleus (identity, always present)
    "tier2": 1200,             // knowledge (workspace docs, scored)
    "tier3": 600,              // temporal (recent events, session)
    "tier4": 600               // peripheral (ambient awareness)
  },
  "effective_budget": 8000,    // iris-adjusted token budget
  "iris_pressure": 0.225,      // pressure at render time (used/size)
  "blocks": [
    {
      "tier": "tier1",
      "name": "nucleus",
      "hash": "a1b2c3",
      "tokens": 800,
      "stability": 100,
      "sources": [
        { "uri": "cog://nucleus/identity", "title": "Identity" }
      ]
    }
  ]
}

Kernel Card Response

Request — GET /v1/card:

{
  "schemaVersion": "1",
  "name": "CogOS Kernel",
  "humanReadableId": "cogos-local",
  "description": "CogOS cognitive process daemon",
  "url": "http://localhost:6931",
  "defaultModel": "cogos/auto",
  "models": [
    {
      "id": "gemma4:e4b",
      "name": "Gemma 4 E4B",
      "provider": "ollama",
      "limits": { "context": 131072, "output": 8192 }
    }
  ],
  "capabilities": {
    "streaming": true,
    "taaAware": true,
    "memoryIntegration": true,
    "modelRouting": true,
    "ucpHeaders": true
  }
}

Data Flow

OpenClaw agent turn
  │
  ├─ 1. Plugin observes iris state (tokens used / available)
  │
  ├─ 2. POST /v1/context/foveated { prompt, iris, profile }
  │     │
  │     └─ CogOS kernel:
  │        ├─ Extract anchor + goal from prompt
  │        ├─ Compute iris pressure (used / size)
  │        ├─ Score workspace chunks via TRM + salience
  │        ├─ Allocate tier budgets based on pressure
  │        ├─ Render context at variable resolution
  │        └─ Return assembled context string + metadata
  │
  ├─ 3. Plugin prepends context to agent's prompt
  │
  ├─ 4. Agent generates response with full workspace awareness
  │
  └─ 5. On compaction: iris opens wider → next turn gets richer context

Error Handling

• All endpoints return null on failure (network error, timeout, non-2xx)
• The plugin degrades gracefully: if the kernel is unavailable, no context is injected and the agent continues without workspace awareness
• Kernel availability is cached for 30 seconds to avoid hammering a dead endpoint
• The before_agent_start hook has priority 10 (runs before memory plugins)

How iris pressure tracking works

The IrisTracker maintains per-session state:

1. Each turn, the tracker estimates tokens used from the message count (messages.length * tokensPerMessage).
2. Before each agent turn, the plugin reads the iris signals and sends them to the CogOS /v1/context/foveated endpoint alongside the user's prompt.
3. The kernel extracts an anchor (foveal center) from the prompt, then renders workspace context at a resolution proportional to the available iris width.
4. On compaction, the iris opens wider — the tracker records the token reduction and subsequent turns get richer context.
5. Precise token counts from model responses can replace the message-count estimate via updateFromUsage().

Pressure ranges:

• 0-30% — Wide open. Full-resolution context from all tiers.
• 30-70% — Narrowing. Lower-priority tiers get compressed or dropped.
• 70-90% — Tight. Only high-salience context survives.
• 90%+ — Critical. Minimal context injection to avoid pushing past the window.

Requirements

• A running CogOS kernel (default: localhost:6931)
• OpenClaw with plugin SDK support
• Node.js 18+ (for fetch and AbortSignal.timeout)

Part of the CogOS ecosystem

• cogos-dev/cogos — The kernel (what it IS)
• cogos-dev/constellation — Distributed trust (how it TRUSTS)
• cogos-dev/mod3 — Modality bus (how it ACTS)
• cogos-dev/skills — Plugin marketplace (what it CAN DO)
• cogos-dev/research — Theory (why it WORKS)
• cogos-dev/charts — Deployment (how it DEPLOYS)
• cogos-dev/desktop — Native app (how you USE it)

License

MIT