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.
Core Versus Enterprise
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).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.
Lifecycle Event
Fires on memory store, recall, boost, decay, threshold crossing, graph relate, or bus collision.
Predicate Match
Evaluates top-level archetype, namespace, substring pattern, and salience bounds with logical AND.
Crossing Cadence
Enforces on_crossing edge semantics, per_memory or global cooldowns, and max_fires ceilings.
Guarded Action
Executes pin, boost, tag, deprecate, notify, broadcast, or SSRF-hardened HMAC-SHA256 webhook.

| Event | Domain | Availability | Firing Condition |
|---|---|---|---|
| on_store | Memory Lifecycle | Core Everywhere | Fires when a memory node is stored via POST /api/v1/agent/nodes, POST /api/v1/agent/ingest, or MCP store_memory. |
| on_recall | Memory Lifecycle | Core Everywhere | Fires when a memory node is returned by hybrid search or hot-context assembly. |
| on_boost | Memory Lifecycle | Core Everywhere | Fires when salience increases via MCP update_memory (action="boost") or POST /api/v1/agent/boost-batch. |
| on_decay | Memory Lifecycle | Core Everywhere | Fires during thermodynamic decay or downward boost/deprecation. Defaults filter_heat_below to 0.25 if no heat bound is set. |
| on_threshold | Memory Lifecycle | Core Everywhere | Edge-triggered (on_crossing by default) when node heat crosses filter_heat_below or filter_heat_above. |
| on_relate | Knowledge Graph | Core Everywhere | Fires when a relationship edge is created via POST /api/v1/agent/graph/relate or MCP relate_memories. |
| on_conflict | Agent Bus | Enterprise Bus | Enterprise Server event_bus only: fires when concurrent sessions edit the same repo-relative file path (alias: territory.conflict). |
| on_milestone | Agent Bus | Enterprise Bus | Enterprise Server event_bus only: fires when a milestone signal is evaluated via ingest or POST /api/v1/triggers/evaluate (alias: milestone.reached). |
| on_solution | Agent Bus | Enterprise Bus | Enterprise Server event_bus only: fires when an agent records a verified fix or debugging breakthrough (alias: solution.discovered). |
| on_intent_overlap | Agent Bus | Enterprise Bus | Enterprise Server event_bus only: fires when active sessions share >= 2 domain focus terms or Jaccard similarity >= 0.25 (alias: intent.overlap). |
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.
Filter Predicates
- Memory TypeSet
filter_memory_typeto any of the 6 archetypes or*. - Namespace FilterSet
filter_namespaceto a readable workspace slug or*. - Label SubstringSet
filter_label_patternfor case-insensitive matching against pointer summaries. - Salience BoundsCombine
filter_heat_belowandfilter_heat_aboveacross0.0..1.0. - Rate CapsConfigure
max_firesandcooldown_seconds(defaults to 60s on Cloud, 0s locally).
Cadence Controls
- Fire ScopeChoose
fire_scope = "global"or"per_memory"for independent node cooldowns. - Evaluation ModeSupports
on_crossing(default edge crossing),while_true,once, orrepeat_n. - Crossing DirectionConfigure
threshold_directionasauto | below | above | either | band. - Target NodesRestrict via
filter_node_idto a single UUID or comma-separated UUID list.
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}.
| Action | Availability | Configuration Payload | Runtime Effect |
|---|---|---|---|
| pin | Core 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. |
| boost | Core 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. |
| notify | Core 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). |
| tag | Core Everywhere | {"tag": "needs-review"} | Appends the normalized tag to golden_index.tags and badges pointer_summary with [needs-review] (alias: "label"). |
| deprecate | Core Everywhere | {"factor": 0.5, "reason": "superseded"} | Multiplies current_heat by factor (clamped 0.05 to 0.95) and marks confidence = "stale" (volatile decay locally). |
| webhook | Core 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. |
| broadcast | Enterprise 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
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
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.// 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"
}
}
}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}",
},
)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" },
},
});# 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"
}'Trigger API Reference
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/triggers | List triggers visible to the caller (?namespace, ?event, ?enabled_only). |
| POST | /api/v1/triggers | Create a trigger in an ACL-writable namespace. |
| PATCH | /api/v1/triggers/:id | Enable or disable a trigger or update filters, cooldowns, and action_config. |
| DELETE | /api/v1/triggers/:id | Delete a trigger by UUID. |
| GET | /api/v1/triggers/history | Inspect recent trigger_log firings (?trigger_id, ?limit). |
| POST | /api/v1/triggers/evaluate | Evaluate matching triggers manually for a given event and node payload. |
| POST | /api/v1/triggers/feedback | Record precision telemetry (helpful | noisy | dismissed | acted_on | false_positive). |
| GET | /api/v1/triggers/feedback | List recorded trigger feedback signals for precision tuning. |
| MCP | create_trigger / list_triggers / update_trigger / delete_trigger | Full trigger lifecycle and firing history (include_history=true) over Stdio or Streamable HTTP MCP. |