Sulcus Memory Skill

Sulcus is a cognitive memory system for AI agents — not a simple key-value store. Every memory is automatically scored, classified, graph-linked, and subject to thermodynamic decay. The system learns what matters and keeps it accessible.

Prerequisites

Required plugin: openclaw-sulcus (install via openclaw plugin install openclaw-sulcus)

Two operating modes:

• Local-only (no credentials needed): All memory stays in ~/.sulcus/data/. Zero network calls. Requires native dylibs (libsulcus_store, libsulcus_vectors) or WASM fallback.
• Cloud mode (requires serverUrl + apiKey): Memories are stored on and recalled from the configured Sulcus server. Embedding (BGE-small-en-v1.5) uses the same apiKey — no separate credentials. Get a key at sulcus.ca.

No additional databases or infrastructure needed by the agent. PostgreSQL, pgvector, and Apache AGE run server-side (managed by the Sulcus server). The plugin communicates via REST API.

What Sulcus Is

• Thermodynamic memory — memories have heat that decays over time and interaction patterns. High-utility memories stay hot; irrelevant ones cool and disappear.
• Apache AGE knowledge graph — temporal graph over all stored memories. Entities and relationships are extracted automatically. Graph queries reveal connections across time.
• SIU v2 pipeline — every memory_store fires: SIVU (utility scoring) → SICU (type classification) → SILU (entity extraction) → AGE graph update → trigger evaluation.
• Guardrails — output guard intercepts agent messages for PII/preference violations before delivery; tool guard evaluates tool calls against stored objectives before execution.
• Session-scoped memory — ephemeral per-conversation scratch-pad, auto-purged on session end.
• Temporal supersession — when newer memories contradict older ones, the older ones are automatically marked and deprioritized.
• Curator (sleep cycle) — background process that reclassifies, consolidates, summarizes, and re-vectorizes memories. No manual cleanup needed.
• Reactive triggers — rules that fire automatically on memory events.
• SIRU — adaptive recall unit that learns per-namespace scoring weights from accumulated recall sessions.

Memory Lifecycle

Storing

memory_store(content, memory_type)
  → SIVU scores utility (0–1)
  → SICU classifies type (if not specified)
  → SILU extracts entities and relationships
  → AGE graph node created/updated
  → Triggers evaluated (on_store)
  → Memory persisted with heat, confidence, provenance

Recalling

memory_recall(query, limit)
  → Semantic embedding search (pgvector)
  → Base score = similarity × sim_weight + heat × heat_weight
  → Keyword overlap boost (exact word matches)
  → Temporal proximity boost (time-referenced queries)
  → Namespace ownership boost (agent's own memories preferred)
  → Diversity filter (MMR-lite — near-duplicates dropped)
  → Temporal supersession penalty (50% on superseded items)
  → Recall-boost applied (heat += boost_delta, spaced repetition)
  → Triggers evaluated (on_recall)
  → Graph context available alongside results

Automatic Context Injection

The plugin automatically injects relevant memories into every turn via before_prompt_build using a multi-signal recall pipeline:

User sends message
  → Signal 1: Semantic Search (query against memory embeddings)
  → Signal 2: Hot Context (top 5 highest-heat memories, no query needed)
  → Signal 3: Entity Context (graph neighbors of entities mentioned in message)
  → Signal 4: Profile (user preferences + facts, periodic refresh)
  → Dedup by memory ID across all signals
  → Diversity Filter (MMR-lite: prevents near-duplicate flooding)
  → Temporal Supersession (older conflicting memories penalized 50%)
  → Composite Scoring: Similarity (40%) + Heat (30%) + Recency (20%) + Source Boost (10%)
  → Token Budget Assembly: top-scored memories packed by heat descending
  → Injected via prependContext every turn

This replaces manual memory_recall for context loading. The agent doesn't need to search — the memory layer surfaces what matters automatically.

Recall Pipeline Details

Topic Shift Detection — The plugin tracks topic tokens (Jaccard overlap) across turns. When the topic is stable (overlap ≥ 0.25), cached results are served instantly with zero API cost. When a topic shift is detected, fresh recall fires automatically. Hard TTL of 5 minutes ensures staleness doesn't accumulate.

Bi-gram Re-ranking — After vector recall, results are re-ranked using phrase-level Dice coefficient against the user's query. This captures multi-word phrase matches that unigram similarity misses. Max 40% score boost. Falls back to server order when no phrase signal exists.

Graph-Hop Expansion — On fresh recall, the top 2 vector results seed an AGE graph traversal. Direct neighbors (1-hop) with heat ≥ 0.2 are folded into the result set (capped at 4 neighbors). This surfaces memories that are related to relevant ones, not just similar. Fully graceful — graph failure never degrades vector recall.

Query Expansion — When vector search returns < 3 results, the entity graph is queried for synonym terms and directly-connected memories. A second vector search fires with the expanded query. Thin recall is rescued without user intervention.

Diversity Filter (MMR-lite) — After recall, near-duplicate memories are removed to prevent context flooding. Ensures a broader spread of unique, relevant information fits within the token budget.

Polarity-Aware Profile — Preference memories are classified as positive ("always", "prefers"), negative ("never", "avoid", "don't"), or neutral. The injected context separates these into <do> and <dont> directive blocks.

Structured XML Context

The injected context block uses structured XML with typed sections:

<sulcus_context token_budget="4000" namespace="my-agent" memories="12">
  <directives>
    <do>
      <memory id="..." heat="85%" type="preference">User prefers TypeScript strict mode</memory>
    </do>
    <dont>
      <memory id="..." heat="72%" type="preference">Never use var declarations</memory>
    </dont>
  </directives>
  <profile>
    <memory id="..." heat="90%" type="fact" age="2d ago">Primary IDE is VS Code</memory>
  </profile>
  <knowledge>
    <memory id="..." heat="60%" type="semantic">Sulcus uses Apache AGE for graph</memory>
    <memory id="..." heat="45%" type="procedural">Deploy: build → test → push → notify</memory>
  </knowledge>
  <recent>
    <memory id="..." heat="30%" type="episodic" age="1h ago" stale="true">Checked logs on April 1</memory>
    <memory id="..." heat="20%" type="episodic" superseded="true">Old deploy process (superseded)</memory>
  </recent>
</sulcus_context>

Each <memory> element includes type, heat, age, and optionally stale="true" (memories >30 days old) and superseded="true" (memories contradicted by newer information). XML-escaped labels prevent structure breaks.

Temporal Supersession

When newer memories contradict older ones, the system automatically identifies the superseded item using:

• Negation markers — explicit contradictions ("no longer", "not anymore", "replaced by")
• Topic overlap — high content similarity between two memories
• Temporal recency — the newer memory wins

Superseded memories receive a 50% score penalty and are tagged with superseded="true" in the XML. They remain visible (providing historical context) but rank below current information. This replaces the older conflict detection system.

Context Rebuild Post-Compaction

When context compaction fires (the model's context window is trimmed from ~150k to ~20k tokens), the plugin:

1. before_compaction — extracts full session knowledge (summary + key decisions + user intents) and stores them as semantic memories
2. Next turn — injects a rich Sulcus context rebuild (configurable token budget, default 4000, max 10000) so the agent regains its bearings from memory rather than degraded compacted context

This ensures continuity through context window resets. Configure with contextRebuild.tokenBudget (default 4000).

Session Lifecycle Hooks

• before_prompt_build — auto-recall injection (main recall path)
• agent_end — SIVU auto-capture from conversation + session memory purge
• before_compaction — pre-compaction session capture + sets rebuild flag
• before_tool_call — tool guard evaluation (when enabled)
• llm_output — output guard scan + optional assistant capture
• message_sending — PII redaction delivery (reversible or replace)

Memory Types — Choose Carefully

Decay rates differ significantly. Wrong type = memory disappears too fast or lingers too long.

Best practices:

• Store user preferences as preference — they survive long and surface reliably
• Store how-tos and processes as procedural — these should never decay quickly
• Store facts as fact — stable, slow decay, always available
• Use episodic for events and session context — fast decay is correct here
• Use semantic for domain concepts and relationships

Auto-Capture

SIVU auto-capture runs on agent_end to mine the conversation for memory-worthy content. It passes user messages through the SIVU quality gate before storing.

Correction detection: When the user corrects the agent ("actually, that's wrong", "no, I meant..."), the auto-capture system detects the correction and heat-boosts related memories that were contradicted — surfacing them more prominently next turn.

Assistant capture: When captureFromAssistant: true, the plugin also captures assistant responses through the SIVU quality gate. Long responses are summarized before storage.

Config:

• autoCapture: true — enable auto-capture (default: false)
• captureFromAssistant: true — also capture assistant responses (default: false)

Guardrails System

Guardrails are disabled by default. Enable them in plugin config under guardrails.

Output Guard

Intercepts agent output before delivery and scans for:

• PII patterns — email addresses, phone numbers, SSNs, credit card numbers, IP addresses (built-in). Custom regex patterns supported.
• Preference violations — output contradicts stored negative preferences ("don't say X", "never do Y"). Fetched from the agent's memory namespace.

Actions on violation:

• redact (default for PII) — replaces matched spans with [REDACTED]. Reversible mode: stores a mapping so redactions can be undone.
• replace (default for preference violations) — replaces the entire output with a configurable message.
• block — cancels output delivery entirely.

Audit trail — every guard event is stored as an episodic memory and written to the inspect buffer (visible via memory_inspect).

Fail modes:

• fail-open (default) — if guard throws an error, output passes through
• fail-closed — if guard throws, output is blocked

{
  "guardrails": {
    "outputGuard": {
      "enabled": true,
      "pii": {
        "enabled": true,
        "patterns": ["email", "phone", "ssn", "credit_card", "ip_address"],
        "onViolation": "redact",
        "reversible": true,
        "customPatterns": [
          { "name": "internal_id", "regex": "\\bINT-\\d{6}\\b" }
        ]
      },
      "preferenceViolation": {
        "enabled": true,
        "onViolation": "replace",
        "replacementMessage": "⚠️ I stopped myself — this output would violate a stored preference."
      },
      "failMode": "fail-open",
      "auditTrail": true
    }
  }
}

Tool Guard

Evaluates tool calls before execution (before_tool_call hook). For sensitive tools, checks whether the call conflicts with stored objectives or user preferences.

Three outcomes:

1. allow — tool runs normally
2. requireApproval — pauses execution, presents the tool call + reason for human review
3. block — hard-blocks the tool call with a reason

Severity levels: info, warning, critical. The requireApprovalThreshold config controls which severity triggers requireApproval.

Tool evaluation logic:

• Allowlist — tools in the allowlist always pass immediately, no evaluation
• Blocklist — tools in the blocklist are always hard-blocked
• Sensitive tools — tools in sensitiveTools go through objective alignment check
• Non-sensitive tools — pass without evaluation

Objective alignment check: Searches agent memory for objectives and preferences related to the tool. If a stored preference explicitly prohibits the action ("never run shell commands", "don't modify files"), the call gets critical severity.

{
  "guardrails": {
    "toolGuard": {
      "enabled": true,
      "sensitiveTools": ["exec", "write", "edit", "delete", "message"],
      "allowlist": ["memory_recall", "memory_store"],
      "blocklist": [],
      "objectiveCheck": true,
      "requireApprovalThreshold": "warning",
      "failMode": "fail-open",
      "auditTrail": true
    }
  }
}

Checking Guardrail Status

Use guardrail_status to see what's active and what's been blocked:

• Active outputGuard/toolGuard config (enabled, patterns, actions)
• Cached negative preference count
• Last 5 blocked/flagged events with reasons

Use memory_inspect for the full debug view including last recall injection details.

Session-Scoped Memory

Short-term scratch-pad for per-conversation context. Memories stored here are automatically purged when the session ends — they never accumulate in the main namespace.

Use cases:

• Intermediate reasoning steps you want to reference later in the same conversation
• User context that's only relevant to this exchange ("user is asking about X project today")
• Draft/work-in-progress notes

session_store(content="User is currently debugging a memory leak in service X", memory_type="episodic")
session_recall(query="what service is the user debugging")

Session memories are stored with high initial heat (0.95) so they surface immediately in the same turn. They're tracked by ID in a module-scope set and deleted on agent_end.

SIRU — Adaptive Recall Unit

SIRU learns which memories are most useful for a given query by analyzing accumulated recall sessions, then replaces the default heuristic scoring with per-namespace learned weights.

How SIRU Works

1. Data Collection (automatic) — Every recall session is logged to the server: query text, memory IDs selected, composite scores, signal sources, token budget vs actual usage, candidate counts.

2. Training — When ≥20 recall sessions have accumulated, trigger training:

   siu_retrain()  →  POST /api/v2/siu/retrain { "model": "siru" }
   

3. Adaptive Scoring — The plugin fetches learned weights every 30 minutes and uses them in composite scoring:

4. Fallback — If no trained weights exist or server is unreachable, heuristic defaults are used.

SIRU Feedback

Submit explicit feedback to accelerate SIRU training:

POST /api/v1/agent/recall-feedback
{ "session_id": 42, "signal": "helpful" }

Valid signals: helpful, unhelpful, partial. Feedback sessions are weighted more heavily during training.

Trigger System

Triggers fire automatically on server-side memory events. Evaluate explicitly with evaluate_triggers.

Events: on_store, on_recall, on_boost, on_decay

Actions: notify, boost, pin, tag, deprecate, webhook, chain

Curator (Sleep Cycle)

Background process that runs independently:

• Reclassifies memories where SICU confidence is low
• Consolidates near-duplicate memories (merges or deprecates)
• Summarizes clusters of episodic memories into semantic nodes
• Re-vectorizes memories whose embeddings are stale
• Resolves conflicts flagged by the supersession system

Runs on a schedule — no manual intervention needed. Use consolidate for manual cleanup.

SILU Output Evaluation

SILU can act as a recursive LM supervisor — evaluating agent outputs against stored memories for alignment issues.

What it checks: Contradictions, preference drift, stale references, hallucination risk.

Enable in plugin config:

{
  "hooks": {
    "llm_output_evaluation": { "enabled": true }
  }
}

When enabled, every LLM response is evaluated fire-and-forget. Misalignment findings are stored as episodic memories.

sulcus.toml Config Layer

File-based configuration at ~/.sulcus/sulcus.toml (or project-level). Provides defaults that the OpenClaw plugin config can override.

Precedence: plugin config (openclaw.json) → sulcus.toml → built-in defaults

Example ~/.sulcus/sulcus.toml:

[recall]
tokenBudget = 6000
profileFrequency = 5
boostOnRecall = true

[decay]
mode = "hybrid"

[autoCapture]
enabled = true
captureFromAssistant = false

[contextRebuild]
enabled = true
tokenBudget = 6000

[guardrails.outputGuard]
enabled = false

[guardrails.toolGuard]
enabled = false

Supports [sections] which map to nested objects. Config values in sulcus.toml are the baseline; openclaw.json plugin config takes precedence.

Tool Reference

Core Memory Tools

Session Memory Tools

Diagnostic Tools

SIU / Training Tools

Maintenance Tools

Cross-Agent Tools (disabled by default)

Enable both in plugin config:

{
  "tools": {
    "memory_share": { "enabled": true },
    "memory_cross_recall": { "enabled": true }
  },
  "sharedNamespaces": ["agent-b"]
}

Temporal Search

Search queries with time references are automatically enhanced. The server parses natural language time expressions and boosts memories from the matching time window.

Supported: yesterday, today, last week, this week, last month, N days ago, last monday/friday/etc., explicit YYYY-MM-DD dates.

memory_recall("what happened yesterday")   → +30% boost for memories from yesterday
memory_recall("deploy issues last week")   → boost for last week's memories
memory_recall("deploy the server")         → no time reference, pure semantic

Temporal search is additive — boosts, not filters. Most relevant content always surfaces.

For programmatic use:

memory_recall(query="deployment issues", time_from="2026-04-01T00:00:00Z", time_to="2026-04-07T23:59:59Z")

Plugin Configuration

All fields in openclaw.json → plugins.entries.openclaw-sulcus.config:

Connection

Recall Behavior

Auto-Capture

Context Rebuild

SILU Output Evaluation

Guardrails

Other

⚠️ Critical: hooks.allowPromptInjection must be true for before_prompt_build to inject context.

Minimal working config (local-only, no network):

{
  "plugins": {
    "entries": {
      "openclaw-sulcus": {
        "enabled": true,
        "config": {
          "agentId": "your-agent",
          "namespace": "your-agent"
        }
      }
    }
  }
}

Cloud mode config (recommended):

{
  "plugins": {
    "entries": {
      "openclaw-sulcus": {
        "enabled": true,
        "hooks": { "allowPromptInjection": true },
        "config": {
          "serverUrl": "https://api.sulcus.ca",
          "apiKey": "YOUR_API_KEY",
          "agentId": "your-agent",
          "namespace": "your-agent",
          "autoRecall": true,
          "autoCapture": true,
          "tokenBudget": 4000,
          "contextRebuild": {
            "enabled": true,
            "tokenBudget": 4000
          }
        }
      }
    }
  }
}

Cloud mode with guardrails:

{
  "plugins": {
    "entries": {
      "openclaw-sulcus": {
        "enabled": true,
        "hooks": { "allowPromptInjection": true },
        "config": {
          "serverUrl": "https://api.sulcus.ca",
          "apiKey": "YOUR_API_KEY",
          "agentId": "your-agent",
          "namespace": "your-agent",
          "autoRecall": true,
          "autoCapture": true,
          "tokenBudget": 4000,
          "guardrails": {
            "outputGuard": {
              "enabled": true,
              "pii": { "enabled": true, "onViolation": "redact" },
              "preferenceViolation": { "enabled": true, "onViolation": "replace" }
            },
            "toolGuard": {
              "enabled": true,
              "requireApprovalThreshold": "warning"
            }
          }
        }
      }
    }
  }
}

Extraction Hints

Domain-specific hints guide SILU's entity extraction without overriding its judgment. Configure in plugin config:

{
  "extractionHints": {
    "entity_types": ["person", "tool", "project", "service"],
    "focus_areas": ["infrastructure", "memory systems", "deployment"],
    "suppress_types": ["location"],
    "expected_type": "procedural",
    "context_note": "This agent manages cloud infrastructure and memory systems"
  }
}

All fields are optional. SILU uses hints as guidance, not commands — it overrides when content clearly indicates otherwise.

Usage Patterns

Start of session

Context is injected automatically via before_prompt_build when autoRecall: true. No manual recall needed — the multi-signal pipeline surfaces your most important memories every turn.

For explicit search when you need specific context:

memory_recall(query="[current task or project]", limit=5)

Capturing preferences

memory_store(content="User prefers TypeScript strict mode", memory_type="preference")

Capturing a process

memory_store(content="Deploy process: build → test → tag → push → notify #releases", memory_type="procedural")

Session scratch-pad

session_store(content="User is debugging a race condition in the scheduler", memory_type="episodic")
session_recall(query="what bug is user debugging")

Checking memory health

memory_profile()         # rich snapshot: hot nodes, preferences, facts, stats
memory_status()          # backend status, recall quality metrics
memory_inspect()         # debug: last recall injection + guardrail events
guardrail_status()       # guardrail config + blocked events

Checking what SIU thinks of a piece of text

siu_label(text="User likes dark mode")
# Returns: { store: true, store_confidence: 0.84, memory_type: "preference" }

Fetching and updating a memory

memory_list(memory_type="preference", sort_by="current_heat")
memory_get(id="uuid-of-memory")
memory_update(id="uuid", is_pinned=true, heat=0.9)

Triggering SIRU retraining

siu_status()    # check if enough signals accumulated
siu_retrain()   # trigger async retrain

Periodic cleanup

consolidate(min_heat=0.1)

Run occasionally to merge near-duplicates and prune cold noise.

Server Recall Tuning

These fields are tuned server-side via PATCH /api/v1/settings/thermo:

Recall Quality Metrics

The plugin tracks recall health metrics across the session, visible via memory_status:

Interaction-Based Decay

Sulcus supports 3 decay modes (configured server-side):

• Time-only — classic: memory cools based on wall-clock time since last access
• Interaction-only — memories decay per agent interaction; great for high-frequency agents
• Hybrid (default) — combination of both; high-utility memories resist decay

High-utility memories (procedural, fact, high-SIVU score) decay slowly. Low-utility noise (episodic, low-SIVU) cools quickly and gets consolidated.

Confidence Levels

Every memory carries a confidence level:

• observed (default) — directly observed fact or event
• inferred — derived from other memories or reasoning
• asserted — explicitly stated by user or system

Troubleshooting

• Plugin not responding — ensure openclaw-sulcus is installed and enabled in ~/.openclaw/openclaw.json. Run openclaw gateway restart after config changes.
• No context injection — check that hooks.allowPromptInjection: true is set. Without it, before_prompt_build can't inject.
• No cloud sync — serverUrl and apiKey required. Get a key at sulcus.ca. Without them, plugin runs local-only.
• Local mode — sulcus-local binary manages embedded PostgreSQL. Check memory_status to confirm backend mode.
• Memories not persisting — verify namespace matches across sessions (agentId / namespace in config). Check that namespace isn't being sanitized to a different value.
• Memories decaying too fast — check decay mode via memory_status. Switch to Hybrid mode server-side, or use procedural/fact types for long-lived knowledge.
• Superseded memories still appearing — this is intentional. Superseded items carry superseded="true" and rank lower, but remain visible as historical context. Delete them with memory_delete if you want them gone entirely.
• Guardrail blocking unexpected output — check guardrail_status for active rules and memory_inspect for the last blocked event. Review stored negative preferences with memory_list(memory_type="preference"). Disable preferenceViolation in config if too aggressive.
• Tool guard requiring approval too often — raise requireApprovalThreshold from warning to critical, or add frequently-used tools to the allowlist.
• Output guard not activating — ensure guardrails.outputGuard.enabled: true AND guardrails.outputGuard.pii.enabled: true (PII sub-section is separately gated).
• Session memories surviving after session end — session memories are purged on agent_end hook. If the gateway was killed mid-session, they may persist. Use memory_list to find and delete any orphaned session memories.
• Context too small / memories missing — increase tokenBudget in plugin config. The default (4000 tokens) fits ~30 memories; increase to 8000+ for large-context models.
• Profile not reflecting recent preferences — lower profileFrequency in config (default: 10 turns). Set to 1 for always-fresh profile (more API calls).
• Recall seems stale within a session — the plugin detects topic shifts automatically. If Jaccard overlap drops below 0.25, fresh recall fires immediately. 5-minute hard TTL ensures refresh even within a stable topic. For immediate refresh, use explicit memory_recall.
• High LLM cache-write costs — verify plugin version ≥ 5.5.1. Earlier versions inject volatile relevance percentages and timestamps that bust the prompt cache on every turn. v5.5.1+ uses stable confidence bands and a recall TTL.
• memory_get/memory_list/memory_update not available — these require cloud backend (serverUrl + apiKey configured). They are not available in local-only mode.
• SIU tools failing — siu_label, siu_status, siu_retrain all require cloud backend. Check that serverUrl and apiKey are set.
• Context not rebuilding after compaction — ensure contextRebuild.enabled is not explicitly set to false. Check logs for pre_compaction_capture events. If the gateway was restarted between compaction and the next turn, the rebuild flag resets (this is correct behavior — the gateway restart itself is a fresh session).
• Agent knocked offline after plugin update — ensure the plugin version matches the server version. The plugin falls back gracefully on older servers but with reduced functionality.