Event Automation

Reactive Triggers

Turn passive memory storage into an event-driven nervous system. Every Sulcus workstation and server runs 6 Core Events and 6 Core Actions, while Sulcus Cloud and Enterprise Server add 4 Agent Bus Events and cross-namespace broadcast.

Six Core EventsSix Core ActionsFour Bus EventsEnterprise Broadcast

Core Versus Enterprise

The 6 Core Events (on_store, on_recall, on_boost, on_decay, on_threshold, on_relate) and 6 Core Actions (pin, boost, notify, tag, deprecate, webhook) execute everywhere—including the free-forever local workstation binary. The 4 Enterprise Bus Events (on_conflict, on_milestone, on_solution, on_intent_overlap) plus the broadcast action run exclusively on Sulcus Enterprise Server (event_bus).
Deterministic Engine

Trigger Execution Pipeline

Triggers evaluate synchronously inside a recursion-guarded task context (MAX_TRIGGER_EVAL_DEPTH = 2) so an action such as boost or tag can never cause a runaway cascade.

Step One

Lifecycle Event

Fires on memory store, recall, boost, decay, threshold crossing, graph relate, or bus collision.

Step Two

Predicate Match

Evaluates top-level archetype, namespace, substring pattern, and salience bounds with logical AND.

Step Three

Crossing Cadence

Enforces on_crossing edge semantics, per_memory or global cooldowns, and max_fires ceilings.

Step Four

Guarded Action

Executes pin, boost, tag, deprecate, notify, broadcast, or SSRF-hardened HMAC-SHA256 webhook.

Reactive Triggers
Sulcus Control Panel Reactive Memory Triggers interface showing active triggers and recent trigger firings
Creating and auditing Reactive Triggers in the Control Panel. Operators can inspect total fire counts, toggle triggers live, and review recent event -> action firings.
EventDomainAvailabilityFiring Condition
on_storeMemory LifecycleCore EverywhereFires when a memory node is stored via POST /api/v1/agent/nodes, POST /api/v1/agent/ingest, or MCP store_memory.
on_recallMemory LifecycleCore EverywhereFires when a memory node is returned by hybrid search or hot-context assembly.
on_boostMemory LifecycleCore EverywhereFires when salience increases via MCP update_memory (action="boost") or POST /api/v1/agent/boost-batch.
on_decayMemory LifecycleCore EverywhereFires during thermodynamic decay or downward boost/deprecation. Defaults filter_heat_below to 0.25 if no heat bound is set.
on_thresholdMemory LifecycleCore EverywhereEdge-triggered (on_crossing by default) when node heat crosses filter_heat_below or filter_heat_above.
on_relateKnowledge GraphCore EverywhereFires when a relationship edge is created via POST /api/v1/agent/graph/relate or MCP relate_memories.
on_conflictAgent BusEnterprise BusEnterprise Server event_bus only: fires when concurrent sessions edit the same repo-relative file path (alias: territory.conflict).
on_milestoneAgent BusEnterprise BusEnterprise Server event_bus only: fires when a milestone signal is evaluated via ingest or POST /api/v1/triggers/evaluate (alias: milestone.reached).
on_solutionAgent BusEnterprise BusEnterprise Server event_bus only: fires when an agent records a verified fix or debugging breakthrough (alias: solution.discovered).
on_intent_overlapAgent BusEnterprise BusEnterprise Server event_bus only: fires when active sessions share >= 2 domain focus terms or Jaccard similarity >= 0.25 (alias: intent.overlap).
Rate Controls

Predicates And Cadence

Trigger filters are top-level fields on the trigger payload (there is no nested condition wrapper object). All specified filters combine with logical AND.

Payload Columns

Filter Predicates

  • Memory TypeSet filter_memory_type to any of the 6 archetypes or *.
  • Namespace FilterSet filter_namespace to a readable workspace slug or *.
  • Label SubstringSet filter_label_pattern for case-insensitive matching against pointer summaries.
  • Salience BoundsCombine filter_heat_below and filter_heat_above across 0.0..1.0.
  • Rate CapsConfigure max_fires and cooldown_seconds (defaults to 60s on Cloud, 0s locally).
Action Config

Cadence Controls

  • Fire ScopeChoose fire_scope = "global" or "per_memory" for independent node cooldowns.
  • Evaluation ModeSupports on_crossing (default edge crossing), while_true, once, or repeat_n.
  • Crossing DirectionConfigure threshold_direction as auto | below | above | either | band.
  • Target NodesRestrict via filter_node_id to a single UUID or comma-separated UUID list.
Action Reference

Actions And Webhooks

Message templates in notify and broadcast interpolate {node_id}, {label}, {content}, {namespace}, {source_namespace}, {target_namespace}, {trigger_name}, {event}, {heat}, {old_heat}, and {memory_type}.

ActionAvailabilityConfiguration PayloadRuntime Effect
pinCore Everywhere{}Sets is_pinned = true on the triggering node (and raises heat to at least 0.90 on the Sulcus API) so it never decays.
boostCore Everywhere{"strength": 0.3, "target": "self"}Adjusts current_heat (clamped -1.0 to 1.0) and increases thermodynamic stability on "self" or an explicit node UUID.
notifyCore Everywhere{"message": "Cooling procedure: {label} ({heat})", "target_namespace": "*"}Logs a structured trigger alert everywhere (and additionally publishes a trigger.notify event when running on Enterprise Server).
tagCore Everywhere{"tag": "needs-review"}Appends the normalized tag to golden_index.tags and badges pointer_summary with [needs-review] (alias: "label").
deprecateCore Everywhere{"factor": 0.5, "reason": "superseded"}Multiplies current_heat by factor (clamped 0.05 to 0.95) and marks confidence = "stale" (volatile decay locally).
webhookCore Everywhere{"url": "https://hooks.example.com/sulcus", "secret": "whsec_...", "headers": {"X-Env": "prod"}}Sends a 5s-timeout HTTP POST with X-Sulcus-Event, X-Sulcus-Trigger, and HMAC-SHA256 X-Sulcus-Signature headers.
broadcastEnterprise Bus{"broadcast_type": "milestone.reached", "message": "{label}", "target_namespaces": ["checkout-web", "qa"]}Enterprise Server event_bus only: fans out a live BusEvent to one or more target namespaces (or "*" / "all" across the tenant).

Signed Webhook Security

Outbound webhook triggers validate target URLs before connecting, blocking loopback, cloud metadata (169.254.0.0/16), RFC1918 private subnets, multicast, and HTTP redirects. When action_config.secret is configured, Sulcus signs the raw JSON body with HMAC-SHA256 and attaches X-Sulcus-Signature: sha256=<hex>.

Deterministic Trigger Authoring

Sulcus intentionally runs zero opaque natural-language trigger daemons. Trigger execution is 100% deterministic Rust (triggers.rs). When an operator asks an agent to surface a rule whenever a topic comes up, the agent calls store_memory followed by create_trigger with explicit filter predicates so operators can audit, toggle, or delete every rule deterministically.
jsonDeterministic Reminder Trigger
// When an operator says "Remind me of our Stripe HMAC rule whenever webhooks come up",
// the agent stores the memory and registers an explicit deterministic trigger via MCP:
{
  "name": "create_trigger",
  "arguments": {
    "name": "remind-stripe-hmac-on-webhook-recall",
    "namespace": "payments-rails",
    "event": "on_recall",
    "action": "boost",
    "filter_label_pattern": "webhook",
    "cooldown_seconds": 60,
    "action_config": {
      "strength": 0.35,
      "target": "0195f410-8a11-7000-8000-000000000010"
    }
  }
}
pythonPython Trigger SDK
from sulcus import Sulcus

client = Sulcus(api_key="sk-...")

# 1. Auto-pin every security playbook stored in security-playbooks
client.create_trigger(
    name="pin-security-playbooks",
    namespace="security-playbooks",
    event="on_store",
    action="pin",
    filter_memory_type="procedural",
    filter_label_pattern="SECURITY",
    cooldown_seconds=0,
)

# 2. Alert peer namespaces when critical runbooks cool below 0.30 heat
client.create_trigger(
    name="alert-cooling-runbooks",
    namespace="payments-rails",
    event="on_threshold",
    action="broadcast",
    filter_memory_type="procedural",
    filter_heat_below=0.30,
    cooldown_seconds=300,
    action_config={
        "fire_scope": "per_memory",
        "evaluation_mode": "on_crossing",
        "broadcast_type": "cooling.alert",
        "target_namespaces": ["payments-rails", "shared-platform"],
        "message": "Runbook [{memory_type}] {label} cooled from {old_heat} to {heat}",
    },
)
typescriptTypeScript Trigger SDK
import { Sulcus } from "sulcus";

const client = new Sulcus({ apiKey: process.env.SULCUS_API_KEY! });

// HMAC-signed webhook whenever an Enterprise OIDC architecture fact is stored
await client.createTrigger({
  name: "webhook-oidc-facts",
  namespace: "shared-platform",
  event: "on_store",
  action: "webhook",
  filterMemoryType: "fact",
  filterLabelPattern: "OIDC",
  cooldownSeconds: 60,
  actionConfig: {
    url: "https://ops.example.com/webhooks/sulcus",
    secret: process.env.WEBHOOK_HMAC_SECRET,
    headers: { "X-Source": "sulcus-shared-platform" },
  },
});
bashEvaluate And Feedback
# Test-fire triggers against a synthetic event payload
curl -X POST https://api.sulcus.ca/api/v1/triggers/evaluate \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "on_milestone",
    "node_namespace": "shared-platform",
    "node_memory_type": "fact",
    "node_label": "Enterprise OIDC token exchange live on Private VPC",
    "node_heat": 0.95
  }'

# Record precision feedback on a fired trigger for telemetry
curl -X POST https://api.sulcus.ca/api/v1/triggers/feedback \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "0195f4c0-7b12-7000-8000-000000000001",
    "signal": "helpful",
    "note": "Surfaced contract update to checkout-web agent immediately"
  }'
Protocol Catalog

Trigger API Reference

MethodEndpointPurpose
GET/api/v1/triggersList triggers visible to the caller (?namespace, ?event, ?enabled_only).
POST/api/v1/triggersCreate a trigger in an ACL-writable namespace.
PATCH/api/v1/triggers/:idEnable or disable a trigger or update filters, cooldowns, and action_config.
DELETE/api/v1/triggers/:idDelete a trigger by UUID.
GET/api/v1/triggers/historyInspect recent trigger_log firings (?trigger_id, ?limit).
POST/api/v1/triggers/evaluateEvaluate matching triggers manually for a given event and node payload.
POST/api/v1/triggers/feedbackRecord precision telemetry (helpful | noisy | dismissed | acted_on | false_positive).
GET/api/v1/triggers/feedbackList recorded trigger feedback signals for precision tuning.
MCPcreate_trigger / list_triggers / update_trigger / delete_triggerFull trigger lifecycle and firing history (include_history=true) over Stdio or Streamable HTTP MCP.
Engineering Dispatches

Architecture Release Notes

Receive technical deep dives on thermodynamic context engineering, System 1 VCR cartridge updates, SulcusBench evaluations, and signed v3.1 engine releases directly from Digital Forge Studios.