@remnic/plugin-openclaw 1.0.2 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joshua Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# @remnic/plugin-openclaw
+
+OpenClaw plugin for Remnic memory. Thin adapter that connects the OpenClaw gateway to [`@remnic/core`](https://www.npmjs.com/package/@remnic/core).
+
+Part of [Remnic](https://github.com/joshuaswarren/remnic), the universal memory layer for AI agents.
+
+## Install
+
+```bash
+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`:
+
+```jsonc
+{
+  "plugins": {
+    "allow": ["openclaw-remnic"],
+    "slots": { "memory": "openclaw-remnic" },
+    "entries": {
+      "openclaw-remnic": {
+        "package": "@remnic/plugin-openclaw"
+      }
+    }
+  }
+}
+```
+
+Then restart the gateway:
+
+```bash
+launchctl kickstart -k gui/501/ai.openclaw.gateway
+```
+
+## 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`](https://www.npmjs.com/package/@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`:
+
+```jsonc
+{
+  "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:
+
+```jsonc
+{
+  "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:
+
+```jsonc
+{
+  "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:
+
+```jsonc
+{
+  "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`](https://www.npmjs.com/package/@remnic/cli) or [`@remnic/server`](https://www.npmjs.com/package/@remnic/server) instead.
+
+## License
+
+MIT

package/dist/{calibration-WZXRJMVP.js → calibration-3JHF25QT.js}

@@ -1,12 +1,12 @@
 import {
   FallbackLlmClient
-} from "./chunk-BIBYVWVY.js";
+} from "./chunk-3SA5F4WT.js";
 import {
   listJsonFiles
 } from "./chunk-5LE4HTVL.js";
 import {
   log
-} from "./chunk-DMGIUDBO.js";
+} from "./chunk-UFU5GGGA.js";
 import "./chunk-MLKGABMK.js";
 
 // ../remnic-core/src/calibration.ts

package/dist/{causal-chain-LA3IQNL6.js → causal-chain-OKDZSDEB.js}

@@ -6,10 +6,10 @@ import {
   stitchCausalChain,
   validateCausalEdge,
   writeChainIndex
-} from "./chunk-HSBPDYF4.js";
-import "./chunk-JGEKL3WH.js";
+} from "./chunk-BXTMZDRT.js";
+import "./chunk-YHH3SXKD.js";
 import "./chunk-5LE4HTVL.js";
-import "./chunk-DMGIUDBO.js";
+import "./chunk-UFU5GGGA.js";
 import "./chunk-MLKGABMK.js";
 export {
   makeEdgeId,

package/dist/{causal-consolidation-YZLBOC7J.js → causal-consolidation-62IFBWHC.js}

@@ -1,20 +1,25 @@
+import {
+  buildExtensionsBlockForConsolidation,
+  runPostConsolidationMaterialize
+} from "./chunk-J2FCINY7.js";
+import {
+  FallbackLlmClient
+} from "./chunk-3SA5F4WT.js";
+import "./chunk-5VTGFKKU.js";
 import {
   readChainIndex,
   resolveChainsDir
-} from "./chunk-HSBPDYF4.js";
+} from "./chunk-BXTMZDRT.js";
 import {
   isRecord
-} from "./chunk-JGEKL3WH.js";
-import {
-  FallbackLlmClient
-} from "./chunk-BIBYVWVY.js";
+} from "./chunk-YHH3SXKD.js";
 import {
   listJsonFiles,
   readJsonFile
 } from "./chunk-5LE4HTVL.js";
 import {
   log
-} from "./chunk-DMGIUDBO.js";
+} from "./chunk-UFU5GGGA.js";
 import "./chunk-MLKGABMK.js";
 
 // ../remnic-core/src/causal-consolidation.ts
@@ -159,7 +164,13 @@ async function deriveCausalPromotionCandidates(options) {
     if (trajectories.length < options.config.minRecurrence) return [];
     const chainsDir = resolveChainsDir(options.memoryDir, options.causalTrajectoryStoreDir);
     const chainIndex = await readChainIndex(chainsDir);
-    const context = formatCausalContext(trajectories, chainIndex);
+    let context = formatCausalContext(trajectories, chainIndex);
+    if (options.pluginConfig) {
+      const extBlock = await buildExtensionsBlockForConsolidation(options.pluginConfig);
+      if (extBlock.length > 0) {
+        context += "\n\n" + extBlock;
+      }
+    }
     const llm = new FallbackLlmClient(options.gatewayConfig);
     if (!llm.isAvailable(options.gatewayAgentId)) {
       log.debug("[cmc] no LLM available for consolidation \u2014 skipping");
@@ -199,7 +210,11 @@ async function synthesizeCausalPreferencesViaLlm(options) {
     return null;
   }
 }
+async function materializeAfterCausalConsolidation(options) {
+  return runPostConsolidationMaterialize("[cmc]", options);
+}
 export {
   deriveCausalPromotionCandidates,
+  materializeAfterCausalConsolidation,
   synthesizeCausalPreferencesViaLlm
 };

package/dist/{causal-retrieval-ITNQBUQM.js → causal-retrieval-5UPIKZ4I.js}

@@ -1,15 +1,15 @@
 import {
   searchCausalTrajectories
-} from "./chunk-BZ27H3BL.js";
+} from "./chunk-RMFPW4VK.js";
 import {
   readChainIndex,
   resolveChainsDir
-} from "./chunk-HSBPDYF4.js";
-import "./chunk-JGEKL3WH.js";
+} from "./chunk-BXTMZDRT.js";
+import "./chunk-YHH3SXKD.js";
 import "./chunk-5LE4HTVL.js";
 import {
   log
-} from "./chunk-DMGIUDBO.js";
+} from "./chunk-UFU5GGGA.js";
 import "./chunk-MLKGABMK.js";
 
 // ../remnic-core/src/causal-retrieval.ts

package/dist/{causal-trajectory-graph-7Z5DD66L.js → causal-trajectory-graph-RQIT37DN.js}

@@ -1,6 +1,6 @@
 import {
   appendEdge
-} from "./chunk-H3SKMYPU.js";
+} from "./chunk-Z7GRLVK3.js";
 import "./chunk-MLKGABMK.js";
 
 // ../remnic-core/src/causal-trajectory-graph.ts

package/dist/{chunk-BIBYVWVY.js → chunk-3SA5F4WT.js}

@@ -1,6 +1,6 @@
 import {
   log
-} from "./chunk-DMGIUDBO.js";
+} from "./chunk-UFU5GGGA.js";
 
 // ../remnic-core/src/json-extract.ts
 function stripCodeFences(text) {