@digitalforgestudios/openclaw-sulcus 7.2.0 → 7.2.1

package/README.md

@@ -1,106 +1,187 @@
 # openclaw-sulcus
 
-Thermodynamic memory + Apache AGE knowledge graph for [OpenClaw](https://openclaw.ai) agents.
+Thermodynamic memory for [OpenClaw](https://openclaw.ai) agents. Every memory is scored, classified, graph-linked, and subject to decay — your agent remembers what matters and forgets what doesn't.
 
-Sulcus is not a simple memory store. It's a cognitive memory system: every memory is scored, classified, graph-linked, and subject to decay. The SIU v2 pipeline processes every store automatically. A sleep-cycle curator keeps things clean. Reactive triggers fire on memory events.
+## What Makes Sulcus Different
 
-## What Sulcus Does
+**Context Engine** — Sulcus doesn't just store memories, it manages your agent's entire context window. The v7.2.0 Context Engine owns compaction, prevents overflow, and builds context constructively from memory rather than patching transcripts.
 
-- **Apache AGE knowledge graph** — temporal graph over all memories; entities, relationships, and provenance tracked automatically
-- **SIU v2 pipeline** — SIVU (utility scoring) → SICU (type classification) → SILU (entity extraction) → AGE graph update → trigger evaluation, fires on every `memory_store`
-- **Interaction-based decay** — 3 modes: Time-only, Interaction-only, Hybrid (default). Memories decay based on access patterns, not just wall-clock time. High-utility memories resist decay.
-- **Curator (sleep cycle)** — background process that reclassifies, consolidates, summarizes, and re-vectorizes memories. Keeps the graph clean without manual intervention.
-- **Relevance-weighted recall** — `score = similarity × 0.7 + heat × 0.3`. Frequently-accessed memories surface faster.
-- **Confidence levels + conflict detection** — memories carry a confidence level (`observed`, `inferred`, `asserted`); the system detects contradictory nodes automatically (v2.3.0+).
-- **Reactive triggers** — rules that fire on `on_store`, `on_recall`, `on_boost`, `on_decay` events. Actions: notify, boost, pin, tag, deprecate, webhook, chain.
-- **Cross-agent sync** — optional cloud sync via `serverUrl`/`apiKey`. Local-first by default.
+**Reactive Triggers** — Rules that fire on memory events (`on_store`, `on_recall`, `on_boost`, `on_decay`). Actions include notify, boost, pin, tag, deprecate, webhook, and chain. Your agent can react to its own memory changes.
+
+**Thermodynamic Decay** — Memories have heat. Frequently accessed memories stay hot; ignored ones cool and eventually fall out of context. Three modes: time-only, interaction-only, or hybrid (default).
 
 ## Install
 
 ```bash
-openclaw plugin install @digitalforgestudios/openclaw-sulcus
+openclaw skill install @digitalforgestudios/openclaw-sulcus
 ```
 
-## Configure
+## Quick Start
 
-Add to `~/.openclaw/openclaw.json`:
+Add to your OpenClaw config (`openclaw.json`):
 
 ```json
-"openclaw-sulcus": {
-  "enabled": true,
-  "config": {
-    "apiKey": "sk-YOUR_KEY_HERE",
-    "agentId": "my-agent",
-    "namespace": "my-agent"
+{
+  "plugins": {
+    "slots": {
+      "memory": "openclaw-sulcus"
+    },
+    "entries": {
+      "openclaw-sulcus": {
+        "enabled": true,
+        "config": {
+          "serverUrl": "https://api.sulcus.ca",
+          "apiKey": "sk-YOUR_KEY_HERE",
+          "agentId": "my-agent",
+          "namespace": "my-agent",
+          "autoRecall": true,
+          "autoCapture": true
+        }
+      }
+    }
   }
 }
 ```
 
 Restart: `openclaw gateway restart`
 
-**No API key?** Plugin starts in local-only mode (no cloud sync). Get a key at [sulcus.ca](https://sulcus.ca) → Dashboard → API Keys.
+**No API key?** The plugin works in local-only mode without cloud sync. Get a key at [sulcus.ca](https://sulcus.ca) → Dashboard → API Keys.
+
+## Features
+
+### Context Engine (v7.0+)
+
+The Context Engine registers as an OpenClaw context provider with `ownsCompaction: true`, giving Sulcus full control over how your agent's context window is managed.
+
+- **Constructive assembly** — Builds context as a constructed view, not a patched log. Recent turns render at full fidelity; older turns use SILU-generated pointer summaries.
+- **Overflow prevention** — Emergency brake at 90% budget, cumulative pressure tracking, adaptive compaction intervals based on growth rate.
+- **Working memory cache** — Per-session cache of tool results with automatic Sulcus ingestion. Large results are stored in memory and replaced with pointers.
+- **Session knowledge extraction** — Automatically identifies and captures decisions, file paths, commands, and intents from the conversation.
+- **26 configurable thresholds** — Every ratio, char limit, and interval is tunable. No hardcoded magic numbers.
+
+### SIU v2 Pipeline
+
+Every `memory_store` fires the full pipeline automatically:
+
+1. **SIVU** — Utility scoring. Quality gate that accepts or rejects content. ONNX inference, <1ms.
+2. **SICU** — Type classification. Auto-classifies into memory types. ONNX inference, <1ms.
+3. **SILU** — Entity extraction + graph relationships. LLM-powered, async.
+4. **AGE graph** — Apache AGE knowledge graph updated with entities and edges.
+5. **Triggers** — Reactive trigger rules evaluated against the event.
+
+### Multi-Signal Recall
+
+Recall combines multiple signals for relevance ranking:
+
+- Semantic similarity (vector search)
+- Full-text search with phrase proximity
+- Thermodynamic heat (access-based decay)
+- Knowledge graph neighbors (entity context)
+- Temporal recency with type-aware half-lives
+- Proper noun and keyword overlap boosts
+- Confidence weighting and conflict detection
+
+### SIRU — Adaptive Scoring
+
+The Sulcus Intelligent Recall Unit learns your agent's recall patterns. After 20+ sessions, SIRU training optimizes scoring weights per namespace. Falls back to heuristic defaults until trained.
+
+### Reactive Triggers
+
+Rules that fire on memory events:
+
+- **Events:** `on_store`, `on_recall`, `on_boost`, `on_decay`
+- **Actions:** notify, boost, pin, tag, deprecate, webhook, chain
+- **SITU training:** Feedback loop improves trigger accuracy over time
+
+### Local-First Architecture (v7.2.0+)
+
+- **SulcusLocalClient** — HTTP client for a localhost sidecar with health tracking
+- **RetryQueue** — Bounded in-memory retry buffer for failed remote writes
+- **Dual-write** — Local-first on store, fire-and-forget sync to cloud
+- **Local-first recall** — Sidecar is the fast path, cloud is the fallback
 
 ## Tools
 
 | Tool | Description |
 |---|---|
-| `memory_store` | Store a memory. SIU pipeline fires automatically: scored, classified, graph-linked. |
-| `memory_recall` | Semantic search with relevance weighting (similarity × 0.7 + heat × 0.3). |
-| `memory_status` | Backend status, namespace info, hot nodes, decay mode, curator state. |
-| `memory_delete` | Delete a memory by ID. Optionally trains SIVU to reject similar content. |
+| `memory_store` | Store a memory. SIU pipeline fires automatically. |
+| `memory_recall` | Multi-signal semantic search with relevance scoring. |
+| `memory_status` | Backend status, namespace info, hot nodes, decay mode. |
+| `memory_delete` | Delete a memory by ID. Optionally trains SIVU rejection. |
 | `consolidate` | Merge and prune cold memories below a heat threshold. |
-| `export_markdown` | Export all memories in current namespace as a Markdown document. |
-| `import_markdown` | Import memories from a Markdown document into current namespace. |
-| `evaluate_triggers` | Evaluate reactive triggers against an event and context object. |
-| `trigger_feedback` | Submit feedback to improve trigger accuracy and SITU scoring. |
+| `export_markdown` | Export all memories as Markdown. |
+| `import_markdown` | Import memories from Markdown. |
+| `evaluate_triggers` | Evaluate reactive triggers against an event. |
+| `trigger_feedback` | Submit feedback to improve trigger accuracy. |
 
-## Memory Types & Decay
-
-Choose the right type — decay rates differ significantly:
+## Memory Types
 
 | Type | Decay Rate | Use For |
 |---|---|---|
 | `episodic` | Fast | Events, sessions, one-off observations |
 | `semantic` | Slow | Concepts, relationships, domain knowledge |
-| `preference` | Slower | User preferences, opinions, style |
+| `preference` | Slower | User preferences, opinions, style choices |
 | `fact` | Slow | Stable factual knowledge |
 | `procedural` | Slowest | How-tos, processes, workflows |
 
-## Configuration Reference
+## Configuration
 
 | Option | Default | Description |
 |---|---|---|
 | `serverUrl` | — | Sulcus cloud URL (e.g. `https://api.sulcus.ca`) |
-| `apiKey` | — | Sulcus API key (`sk-...`) |
-| `agentId` | — | Agent identifier for namespacing |
-| `namespace` | same as `agentId` | Memory namespace |
-| `autoRecall` | `false` | Inject relevant memories into context before each turn |
-| `autoCapture` | `false` | Auto-store important info from conversations |
-| `maxRecallResults` | `5` | Max memories injected on auto-recall |
+| `apiKey` | — | Sulcus API key |
+| `agentId` | — | Agent identifier |
+| `namespace` | `agentId` | Memory namespace |
+| `autoRecall` | `false` | Inject relevant memories before each turn |
+| `autoCapture` | `false` | Auto-store important conversation content |
+| `maxRecallResults` | `5` | Max memories injected per turn |
 | `minRecallScore` | `0.3` | Min relevance score for auto-recall (0–1) |
-| `boostOnRecall` | `true` | Boost heat when a memory is recalled (spaced repetition) |
-| `captureOnCompaction` | `true` | Preserve memories before context compaction |
+| `boostOnRecall` | `true` | Heat boost on recall (spaced repetition) |
+| `captureOnCompaction` | `true` | Preserve memories before compaction |
 | `captureOnReset` | `true` | Capture session summary on `/reset` |
-| `trackSessions` | `false` | Record session start/end as episodic memories |
-| `captureFromAssistant` | `false` | Also capture from assistant messages |
-| `captureToolResults` | `false` | Capture significant tool results |
-| `captureLlmInsights` | `false` | Capture assistant decisions/preferences |
-| `maxCapturePerTurn` | `3` | Max auto-captures per agent turn |
+| `captureFromAssistant` | `false` | Capture from assistant messages |
+| `maxCapturePerTurn` | `3` | Max auto-captures per turn |
+| `tokenBudget` | `10000` | Token budget for context injection |
+| `maxRecallChars` | `2000` | Max chars per recalled memory |
+
+### Context Engine Config
+
+```json
+{
+  "contextEngine": {
+    "compactMode": "smart",
+    "thresholds": {
+      "compactionTriggerRatio": 0.75,
+      "trimTriggerRatio": 0.65,
+      "largeResultChars": 3000,
+      "emergencyBrakeRatio": 0.90,
+      "emergencyHeadChars": 250,
+      "emergencyTailChars": 250,
+      "cumulativePressureChars": 50000,
+      "highGrowthTokensPerTurn": 10000
+    }
+  }
+}
+```
 
 ## Hooks
 
-| Hook | Default | Description |
-|---|---|---|
-| `before_prompt_build` | ON | Inject memory awareness context |
-| `before_agent_start` | ON | Auto-recall relevant memories |
-| `agent_end` | ON | Post-turn processing (capture, triggers) |
+| Hook | Description |
+|---|---|
+| `before_prompt_build` | Injects memory awareness + hot context |
+| `before_agent_start` | Auto-recall relevant memories for the turn |
+| `agent_end` | Post-turn capture, triggers, knowledge extraction |
+| `build_context` | Context Engine assembly (when ownsCompaction enabled) |
+| `on_compaction` | Memory preservation before context compaction |
+| `on_reset` | Session summary capture |
 
 ## Links
 
-- [sulcus.ca](https://sulcus.ca) — sign up, dashboard, docs
-- [npm](https://www.npmjs.com/package/@digitalforgestudios/openclaw-sulcus) — `@digitalforgestudios/openclaw-sulcus`
-- [GitHub](https://github.com/digitalforgeca/sulcus) — source, issues
+- **Website:** [sulcus.ca](https://sulcus.ca)
+- **npm:** [@digitalforgestudios/openclaw-sulcus](https://www.npmjs.com/package/@digitalforgestudios/openclaw-sulcus)
+- **GitHub:** [digitalforgeca/sulcus](https://github.com/digitalforgeca/sulcus)
+- **OpenClaw:** [openclaw.ai](https://openclaw.ai)
 
 ## License
 
-MIT — [Digital Forge Studios Inc.](https://sulcus.ca)
+MIT — [Digital Forge Studios Inc.](https://dforge.ca)

package/index.js

@@ -9599,7 +9599,7 @@ ${res.items.length} shown${res.total ? ` of ${res.total}` : ""}`);
     const assemblyMode = pluginConfig?.contextEngine?.assemblyMode ?? "passthrough";
     const compactMode = pluginConfig?.contextEngine?.compactMode ?? "smart";
     if (contextEngineEnabled && typeof api.registerContextEngine === "function") {
-      const ceVersion = "7.2.0";
+      const ceVersion = "7.2.1";
       const ceThresholds = pluginConfig?.contextEngine?.thresholds ?? {};
       api.registerContextEngine("openclaw-sulcus", async () => {
         let delegateCompaction;
@@ -9623,7 +9623,7 @@ ${res.items.length} shown${res.total ? ` of ${res.total}` : ""}`);
         return engine;
       });
       contextEngineActive = true;
-      logger.info(`sulcus: context engine registered (v7.2.0, ownsCompaction: true, assembly: ${assemblyMode})`);
+      logger.info(`sulcus: context engine registered (v7.2.1, ownsCompaction: true, assembly: ${assemblyMode})`);
     } else if (contextEngineEnabled) {
       logger.warn("sulcus: contextEngine.enabled=true but api.registerContextEngine not available \u2014 skipping");
     } else {

package/index.ts

@@ -7114,7 +7114,7 @@ ${finalContent}`;
     const assemblyMode = (pluginConfig?.contextEngine as any)?.assemblyMode ?? "passthrough";
     const compactMode = (pluginConfig?.contextEngine as any)?.compactMode ?? "smart";
     if (contextEngineEnabled && typeof (api as any).registerContextEngine === "function") {
-      const ceVersion = "7.2.0";
+      const ceVersion = "7.2.1";
       const ceThresholds = (pluginConfig?.contextEngine as any)?.thresholds ?? {};
       (api as any).registerContextEngine("openclaw-sulcus", async () => {
         // Lazy-load delegate at factory time
@@ -7140,7 +7140,7 @@ ${finalContent}`;
         return engine;
       });
       contextEngineActive = true;
-      logger.info(`sulcus: context engine registered (v7.2.0, ownsCompaction: true, assembly: ${assemblyMode})`);
+      logger.info(`sulcus: context engine registered (v7.2.1, ownsCompaction: true, assembly: ${assemblyMode})`);
     } else if (contextEngineEnabled) {
       logger.warn("sulcus: contextEngine.enabled=true but api.registerContextEngine not available — skipping");
     } else {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "version": "7.2.0",
-  "description": "Sulcus — thermodynamic memory + Apache AGE knowledge graph for OpenClaw agents. v6.0: Multi-signal recall (semantic + hot-context + entity-graph + profile), configurable guardrails (outputGuard + toolGuard), token budget enforcement, context rebuild post-compaction, sulcus.toml config layer, SIRU training data logging, session-scoped memory, batch heat-boost. SIU v2 pipeline (SIVU/SICU/SILU/SITU/SIRU). Interaction-based decay. Curator sleep-cycle. Cross-agent sync.",
+  "version": "7.2.1",
+  "description": "Thermodynamic memory for OpenClaw agents. Context Engine with constructive assembly and overflow prevention. SIU v2 pipeline (SIVU/SICU/SILU), Apache AGE knowledge graph, reactive triggers, multi-signal recall, interaction-based decay, local-first architecture with cloud sync.",
   "keywords": [
     "openclaw",
     "openclaw-plugin",