@remnic/plugin-openclaw

OpenClaw plugin for Remnic memory. Thin adapter that connects the OpenClaw gateway to @remnic/core.

Part of Remnic, the universal memory layer for AI agents.

Install

openclaw plugins install @remnic/plugin-openclaw --pin

Or ask your OpenClaw agent:

Install the @remnic/plugin-openclaw plugin and configure it as my memory system.

Configure

Add the plugin to your openclaw.json:

{
  "plugins": {
    "allow": ["openclaw-remnic"],
    "slots": { "memory": "openclaw-remnic" },
    "entries": {
      "openclaw-remnic": {
        "package": "@remnic/plugin-openclaw"
      }
    }
  }
}

Then restart the gateway:

launchctl kickstart -k gui/501/ai.openclaw.gateway

Benchmarking The OpenClaw Chain

The benchmark CLI can now exercise the real OpenClaw-backed answer path instead of only the stripped retrieval harness. Use the openclaw-chain runtime profile to load the Remnic plugin config from openclaw.json, route answer generation through the configured gateway chain, and optionally attach a provider-backed judge:

remnic bench run longmemeval \
  --runtime-profile openclaw-chain \
  --openclaw-config ~/.openclaw/openclaw.json \
  --gateway-agent-id memory-primary

remnic bench run longmemeval \
  --runtime-profile openclaw-chain \
  --openclaw-config ~/.openclaw/openclaw.json \
  --gateway-agent-id memory-primary \
  --judge-provider openai \
  --judge-model gpt-5.4-mini

To compare the stripped harness, direct Remnic runtime, and OpenClaw chain in a single pass, run a profile matrix:

remnic bench run longmemeval \
  --matrix baseline,real,openclaw-chain \
  --openclaw-config ~/.openclaw/openclaw.json \
  --remnic-config ~/.config/remnic/config.json

Each stored result records its runtimeProfile, provider metadata, and the resolved Remnic config so benchmark comparisons can distinguish retrieval-only runs from real runtime and OpenClaw chain runs.

What it does

This plugin hooks into the OpenClaw gateway lifecycle:

• gateway_start -- initializes the Remnic memory engine
• before_agent_start / before_prompt_build -- injects relevant memories into the agent's context
• agent_end -- buffers the conversation turn for extraction
• before_compaction / after_compaction -- saves checkpoints and triggers session reset on context compaction
• before_reset -- bounded flush of the in-flight buffer before OpenClaw discards a session
• commands.list -- exposes Remnic slash-command descriptors to the command palette
• session_start / session_end -- session lifecycle tracking
• before_tool_call / after_tool_call -- tool usage observation for analytics
• llm_output -- LLM token usage tracking
• subagent_spawning / subagent_ended -- subagent lifecycle observation
• Tools -- registers memory_search, memory_get, memory_stats, and other agent tools
• Commands -- provides CLI commands for memory management

All memory processing uses @remnic/core. Data stays on your local filesystem as plain markdown files.

Slot Selection

Remnic is an exclusive memory-slot plugin. When plugins.slots.memory points to another plugin, Remnic now validates that mismatch and either errors or loads passively depending on slotBehavior:

{
  "plugins": {
    "entries": {
      "openclaw-remnic": {
        "config": {
          "slotBehavior": {
            "requireExclusiveMemorySlot": true,
            "onSlotMismatch": "error"
          }
        }
      }
    }
  }
}

Passive mode keeps the tool/service surface available but skips prompt injection and extraction hooks so two memory plugins do not race each other.

Supported OpenClaw Memory Features

Remnic supports the following OpenClaw memory integration points:

Memory Prompt Injection

| Feature | Status | Since | |---------|--------|-------| | before_agent_start hook (legacy) | Supported | 2025.x | | before_prompt_build hook (new SDK) | Supported | 2026.3.22 | | registerMemoryPromptSection() (structured builder) | Supported | 2026.3.22 | | registerMemoryCapability() (unified capability) | Supported | 2026.4.5 |

Public Artifacts (memory-wiki bridge)

| Feature | Status | Since | |---------|--------|-------| | publicArtifacts.listArtifacts() | Supported | 2026.4.5 |

When registerMemoryCapability is available, Remnic registers a publicArtifacts provider that exposes wiki-safe memory files:

• facts/ -- extracted knowledge (dated subdirectories)
• entities/ -- entity knowledge graph
• corrections/ -- fact corrections
• artifacts/ -- structured artifacts
• profile.md -- agent identity summary

Private runtime state (state/, questions/, transcripts/, archive/, buffers) is never exposed.

With this feature, openclaw wiki status reports Remnic artifacts, and memory-wiki bridge mode can discover and ingest them.

Session Lifecycle

| Feature | Status | Since | |---------|--------|-------| | session_start / session_end hooks | Supported | 2026.3.22 | | before_compaction / after_compaction hooks | Supported | 2026.3.22 | | before_reset hook | Supported | 2026.4.10 | | commands.list runtime discovery | Supported | 2026.4.10 | | api.resetSession() (compaction reset) | Supported | 2026.3.22 | | Checkpoint saves before compaction | Supported | 2026.3.22 |

Reset handling is configurable:

{
  "plugins": {
    "entries": {
      "openclaw-remnic": {
        "config": {
          "flushOnResetEnabled": true,
          "beforeResetTimeoutMs": 2000
        }
      }
    }
  }
}

The reset path clears per-session prompt caches and workspace override state. If flushOnResetEnabled is true, Remnic also attempts a bounded extraction flush before the reset completes.

Session-scoped recall controls are exposed through OpenClaw's command discovery surface:

• remnic off / remnic on
• remnic status
• remnic clear
• remnic stats
• remnic flush

When verbose mode is enabled, Remnic prints its recall decision header inline and can optionally persist JSONL recall transcripts under <memoryDir>/state/plugins/openclaw-remnic/transcripts/.

Observation Hooks

| Feature | Status | Since | |---------|--------|-------| | before_tool_call / after_tool_call | Supported | 2026.3.22 | | llm_output (token tracking) | Supported | 2026.3.22 | | subagent_spawning / subagent_ended | Supported | 2026.3.22 |

Dreaming

OpenClaw's dreaming feature (background memory consolidation) is handled by OpenClaw's built-in memory-core extension. Remnic implements its own consolidation pipeline (extraction, deduplication, graph maintenance, hourly summaries) that runs independently of OpenClaw's dreaming system. The two systems are complementary -- Remnic's consolidation handles the heavy memory extraction, while OpenClaw's dreaming (if enabled alongside Remnic) can further organize knowledge.

The plugin manifest now accepts the OpenClaw dreaming config block directly so newer runtimes do not reject the config at validation time, and the OpenClaw adapter now injects recent diary entries as ## Recent Dreams (Remnic) when the journal contains entries. The adapter also imports DREAMS.md entries into Remnic storage as memoryKind: "dream" with stable provenance so file-watch replays stay idempotent:

{
  "plugins": {
    "entries": {
      "openclaw-remnic": {
        "config": {
          "dreaming": {
            "enabled": false,
            "journalPath": "DREAMS.md",
            "maxEntries": 500,
            "injectRecentCount": 3,
            "minIntervalMinutes": 120,
            "narrativeModel": "gpt-5.2",
            "narrativePromptStyle": "reflective",
            "watchFile": true
          }
        }
      }
    }
  }
}

When Remnic's consolidation pass produces a reflective multi-session summary and the interval gate is satisfied, the OpenClaw adapter appends a new dream entry back to DREAMS.md through the shared writer using the OpenAI Responses API.

The shared @remnic/core surface parsers also understand HEARTBEAT.md. The OpenClaw adapter imports those entries as memoryKind: "procedural", gates normal recall during heartbeat-triggered runs, injects the active heartbeat plus ## Previous Runs, and skips episodic buffering for heartbeat turns by default. Detection can use explicit runtime metadata, a documented heuristic fallback, or auto to prefer runtime metadata and fall back when needed. All of that logic stays in the OpenClaw adapter; standalone/core remains host-agnostic.

Codex Compatibility

Remnic now advertises and parses a dedicated codexCompat block for bundled Codex-provider safety work:

{
  "plugins": {
    "entries": {
      "openclaw-remnic": {
        "config": {
          "codexCompat": {
            "enabled": false,
            "threadIdBufferKeying": true,
            "compactionFlushMode": "auto",
            "fingerprintDedup": true
          }
        }
      }
    }
  }
}

codexCompat.enabled defaults to false, so operators only opt into bundled Codex thread buffering and compaction behavior when they explicitly enable it.

This governs Remnic's own buffering and extraction behavior only. Remnic still uses its own extraction auth path; OpenClaw's bundled Codex provider auth does not replace Remnic's extraction credentials.

Bridge Mode

| Feature | Status | |---------|--------| | Embedded mode (in-process EMO + HTTP :4318) | Supported | | Delegate mode (connects to running daemon) | Supported | | Auto-detection (daemon running = delegate) | Supported |

Standalone usage

If you're not using OpenClaw, use @remnic/cli or @remnic/server instead.

License

MIT