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#

text

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#

text

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:

text

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:

xml

<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.

TypeDecayUse ForepisodicFastEvents, sessions, one-off observationssemanticSlowConcepts, relationships, domain knowledgepreferenceSlowerUser preferences, opinions, style choicesfactSlowStable factual knowledge, ground truthproceduralSlowestHow-tos, processes, workflows, playbooks

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

json

{
  "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.

json

{
  "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

text

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: text

   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:

WeightDefaultControlssimilarity_weight0.40Semantic similarity signalheat_weight0.30Thermodynamic heat signalrecency_weight0.20Time since last updatesource_boost_semantic0.00Boost for semantic search resultssource_boost_hot0.05Boost for hot-context resultssource_boost_entity0.10Boost for graph entity neighborssource_boost_profile0.15Boost for preference + fact results

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

SIRU Feedback#

Submit explicit feedback to accelerate SIRU training:

text

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:

json

{
  "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:

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#

ToolWhat It Doesmemory_storeStore a memory. SIU pipeline (SIVU → SICU → SILU) fires automatically.memory_recallSemantic search with relevance weighting, diversity filter, and supersession.memory_getFetch a specific memory by UUID. Returns full details including graph edges and metadata. (cloud only)memory_listBrowse memories with pagination, type filter, sort by heat/date. (cloud only)memory_updateUpdate content, type, pinned status, or heat on an existing memory in-place. Preserves graph edges. (cloud only)memory_deleteDelete by ID. Optional SIVU training to reject similar content.memory_statusBackend status, hot nodes, decay mode, curator state, recall quality metrics.memory_profileRich memory health snapshot: type distribution, hot nodes, top preferences and facts.memory_namespaceSwitch the recall namespace at runtime. Useful for reading from project-specific or shared namespaces.

Session Memory Tools#

ToolWhat It Doessession_storeStore ephemeral context for the current conversation only. Auto-purged on session end.session_recallSearch only current session's memories (not prior sessions).

Diagnostic Tools#

ToolWhat It Doesmemory_inspectDebug window: last recall injection details, last 10 guardrail events, blocked items.guardrail_statusActive guardrail config, negative preference cache, last 5 blocked events.

SIU / Training Tools#

ToolWhat It Doessiu_labelClassify text through SIU v2 — SIVU store/reject decision + SICU type classification.siu_statusCheck SIU v2 model availability, deployed versions, training signal statistics.siu_retrainTrigger async retrain of SIU v2 models from accumulated training signals.trigger_feedbackRecord feedback on a trigger fire for SITU training.

Maintenance Tools#

ToolWhat It DoesconsolidateMerge and prune cold memories below a heat threshold.export_markdownExport all namespace memories as Markdown.import_markdownImport memories from a Markdown document.evaluate_triggersEvaluate reactive triggers against an event + context.evaluate_output(MCP) Evaluate LLM output against memory for semantic alignment.

Cross-Agent Tools (disabled by default)#

ToolWhat It Doesmemory_shareShare a memory with another agent's namespace.memory_cross_recallSearch another agent's memories for cross-agent context.

Enable both in plugin config:

json

{
  "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.

text

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:

text

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#

FieldTypeDefaultDescriptionserverUrlstring—Sulcus server URL (e.g., https://api.sulcus.ca). Leave empty for local-only mode.apiKeystring—API key from sulcus.ca. Required for cloud mode.agentIdstring—Agent identifier.namespacestring—Memory namespace (usually same as agentId). Sanitized to lowercase, hyphen-normalized.

Recall Behavior#

FieldTypeDefaultDescriptionautoRecallbooleanfalseEnable automatic multi-signal context injection via before_prompt_build. Opt-in.tokenBudgetnumber4000Max tokens for injected context block. Increase to 8000+ for large-context models (Opus, Gemini).profileFrequencynumber10Refresh profile (preferences + facts) every N turns. Turn 1 always includes full profile. Lower = fresher but more API calls.boostOnRecallbooleantrueApply spaced-repetition heat boost to recalled memories.maxRecallResultsnumber5Max memories per search.

Auto-Capture#

FieldTypeDefaultDescriptionautoCapturebooleanfalseEnable SIVU auto-capture on agent_end and compaction. Opt-in.captureFromAssistantbooleanfalseAlso capture assistant responses through SIVU quality gate.

Context Rebuild#

FieldTypeDefaultDescriptioncontextRebuild.enabledbooleantrueInject rich Sulcus context after compaction instead of relying on degraded compacted summary.contextRebuild.tokenBudgetnumber4000Max tokens for post-compaction rebuild (max 10000).

SILU Output Evaluation#

FieldTypeDefaultDescriptionhooks.llm_output_evaluation.enabledbooleanfalseEvaluate every LLM response against stored memories for alignment.

Guardrails#

FieldTypeDefaultDescriptionguardrails.outputGuard.enabledbooleanfalseEnable output guard (PII + preference violation scanning).guardrails.outputGuard.pii.enabledbooleanfalseEnable PII pattern scanning within output guard.guardrails.outputGuard.pii.patternsstring[]all built-inActive PII patterns: email, phone, ssn, credit_card, ip_address.guardrails.outputGuard.pii.onViolationstring"redact"Action on PII: redact, replace, or block.guardrails.outputGuard.pii.reversiblebooleantrueStore redaction mapping for later reversal.guardrails.outputGuard.pii.customPatternsarray[]Custom PII patterns: [{ name, regex, replacement? }].guardrails.outputGuard.preferenceViolation.enabledbooleantrueScan output against negative preferences.guardrails.outputGuard.preferenceViolation.onViolationstring"replace"Action: replace, warn, or block.guardrails.outputGuard.preferenceViolation.replacementMessagestringbuilt-inMessage to replace output with on preference violation.guardrails.outputGuard.failModestring"fail-open"``fail-open (pass on error) or fail-closed (block on error).guardrails.outputGuard.auditTrailbooleantrueStore guard events as episodic memories.guardrails.toolGuard.enabledbooleanfalseEnable tool guard (objective alignment check before sensitive tool calls).guardrails.toolGuard.sensitiveToolsstring[]["exec","write","edit","delete","message"]Tools that trigger objective alignment check.guardrails.toolGuard.allowliststring[][]Tools that always pass without evaluation.guardrails.toolGuard.blockliststring[][]Tools that are always blocked.guardrails.toolGuard.objectiveCheckbooleantrueSearch memory for objectives before evaluating sensitive tools.guardrails.toolGuard.requireApprovalThresholdstring"warning"Severity that triggers requireApproval: info, warning, or critical.guardrails.toolGuard.failModestring"fail-open"``fail-open or fail-closed.guardrails.toolGuard.auditTrailbooleantrueStore tool guard events as episodic memories.

Other#

FieldTypeDefaultDescriptionimportHistorybooleanfalseOne-time import of MEMORY.md and daily notes from OpenClaw workspace into Sulcus. Runs once then marks itself done.extractionHintsobject—Domain hints for SILU entity extraction. See Extraction Hints below.

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

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

json

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

Cloud mode config (recommended):#

json

{
  "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:#

json

{
  "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:

json

{
  "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"
  }
}

FieldTypeDescriptionentity_typesstring[]Entity types expected in this domainfocus_areasstring[]Domain focus areassuppress_typesstring[]Entity types to suppress (e.g., ["location"] if irrelevant)expected_typestringSoft hint for expected memory type — SILU may overridecontext_notestringFree-form context note (max 500 chars, injected verbatim into SILU prompt)

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:

text

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

Capturing preferences#

text

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

Capturing a process#

text

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

Session scratch-pad#

text

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#

text

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#

text

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

Fetching and updating a memory#

text

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#

text

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

Periodic cleanup#

text

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:

FieldDefaultEffectrecall.similarity_weight0.7Weight for semantic similarityrecall.heat_weight0.3Weight for memory heatrecall.keyword_weight0.15Boost for exact word matchesrecall.temporal_max_boost0.4Max boost for time-referenced queriesrecall.temporal_decay_days7.0Days over which temporal boost decaysrecall.namespace_boost0.1Boost for agent's own namespace memories

Recall Quality Metrics#

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

MetricDescriptionfresh_recallsTurns where a fresh API call was made (topic shifted)cache_hitsTurns where cached recall was served (topic stable)total_items_servedCumulative recall items injected across all turnszero_result_turnsTurns where recall returned nothinggraph_hop_contribTotal graph-hop items folded into recallgraph_hop_turnsTurns with at least one graph-hop itemavg_relevanceAverage heat of recalled items (proxy for relevance)

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.