Protocol Specification

API Reference

Complete protocol specification for the Sulcus API (https://api.sulcus.ca, Docker Private VPC appliances, and the local 127.0.0.1:4203 sidecar) plus Streamable HTTP and Stdio Model Context Protocol.

REST JSON SSEStreamable HTTP MCPTenant Rate QuotasOpenAPI Specification
Transport Security

Authentication And Quotas

All /api/v1/* tenant endpoints accept SHA-256 hashed API keys (sk-...), Enterprise OIDC RS256 JWTs, or Air-Gap HS256 session tokens.

Required Header

Bearer Token

Send Authorization: Bearer <token> (or X-API-Key) with an sk-... API key or session JWT.
Workstation Lease

Machine Fingerprint

Header X-Sulcus-Machine-Id passes the deterministic UUIDv5 hardware fingerprint sent automatically by sulcus CLI and IDE plugins.
Scope Override

Namespace Header

Header X-Namespace overrides the default workspace namespace for MCP and REST calls, validated against Two-Gate Namespace ACL.
Rate Ceiling

Request Quotas

Authenticated tenant routes allow 300 req/min per tenant (public routes allow 30 req/min per IP) with a 2 MB JSON body limit.
bashAuthenticated Hybrid Search
# Standard authenticated REST call with workstation seat binding and namespace override
curl -X POST https://api.sulcus.ca/api/v1/agent/search \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "X-Sulcus-Machine-Id: 8b4d0e9c-21f4-5a9c-9d12-40f91a82c311" \
  -H "X-Namespace: payments-rails" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Stripe webhook HMAC verification and timestamp drift",
    "limit": 8
  }'

License Continuity Guarantee

If an enterprise Private VPC or Air-Gapped license enters post-grace expiry (expired_readonly), all GET, hybrid search, recall, and graph read endpoints remain 100% operational so engineers never lose access to institutional memory, while mutating writes return 402 or 403 until renewed. Cross-namespace reads denied by ACL always return 404 Not Found to prevent namespace enumeration.
HTTP Endpoints

REST Route Catalog

Filter by subsystem below. Every route listed here is mounted directly in the production Sulcus router.

Health And Discovery

Unauthenticated liveness probes, deployment auth mode discovery, Bearer verification, and machine-readable OpenAPI 3.1 schemas.

MethodEndpointPurpose
GET
/health
Unauthenticated service liveness and engine readiness probe.
GET
/api/v1/health
Versioned v1 engine liveness, subsystem readiness, and build provenance probe.
GET
/openapi.json
Machine-readable OpenAPI 3.1 specification (also served at /openapi.yaml).
GET
/api/v1/auth/mode
Public discovery of deployment auth mode (cloud | connected_onprem | airgapped) and license state.
GET
/api/v1/auth/verify
Verify current Bearer token or sk-... key and return resolved tenant and namespace scope.

Memories And Sync

Golden Index CRUD, single-pass turn ingestion, core memory blocks, PII scanning, and local-first CRDT delta sync.

MethodEndpointPurpose
POST
/api/v1/agent/nodes
Store a memory node (aliases: POST /api/v1/agent/memory, POST /api/v1/agent/store).
GET
/api/v1/agent/nodes
List memories with ?namespace, ?memory_type, ?is_pinned, ?limit, ?offset (alias: GET /api/v1/agent/memory).
GET
/api/v1/agent/nodes/:id
Fetch full memory Territory and metadata by UUID (alias: GET /api/v1/agent/memory/:id).
PATCH
/api/v1/agent/nodes/:id
Update content (Territory), pointer_summary, memory_type, current_heat, decay_class, min_heat, or is_pinned.
DELETE
/api/v1/agent/nodes/:id
Soft-archive a memory node out of active working recall by UUID (restorable via POST /api/v1/agent/restore).
POST
/api/v1/agent/nodes/batch
Store a batch of memory nodes in one request.
POST
/api/v1/agent/nodes/bulk
Bulk delete memory nodes by UUID array.
POST
/api/v1/agent/nodes/bulk-patch
Bulk update pin state, namespace, or archetype across multiple nodes.
GET
/api/v1/agent/hot_nodes
Retrieve highest-salience active working memory nodes.
GET
/api/v1/agent/core-memory
Read structured core memory blocks (identity, preferences, current_focus).
PATCH
/api/v1/agent/core-memory
Update structured core memory blocks for an agent namespace.
POST
/api/v1/agent/ingest
Unified turn ingestion: single-pass embedding, MemPalace prep, System 1 VCR gating, entity linking, conflict checks, and trigger evaluation.
POST
/api/v1/agent/sync
CRDT WAL delta synchronization for local-first sulcus sidecars.
POST
/api/v1/agent/scan-pii
Scan candidate text for PII patterns prior to storage.
GET
/api/v1/agent/storage
Inspect node counts, storage utilization, and quota limits.
GET
/api/v1/agent/memory/status
Summarize active memory index health and counts.

Hybrid Search

Hybrid cosine + BM25 + graph spreading activation search, token-budgeted hot-context assembly, and recall analytics.

MethodEndpointPurpose
POST
/api/v1/agent/search
Hybrid cosine + BM25 + graph resonance + recency search across primary, global, and linked namespaces.
POST
/api/v1/agent/hot-context
Assemble token-budgeted working context for PreInvocation prompt injection.
POST
/api/v1/agent/entity-context
Retrieve entity-anchored memories and 1-hop knowledge graph context.
POST
/api/v1/agent/evaluate-output
Score generated agent output against stored constraints and surface contradictions.
POST
/api/v1/agent/boost-batch
Reinforce heat and stability across an array of recalled node UUIDs.
POST
/api/v1/agent/recall-log
Record recall telemetry for System 1 VCR adaptive retrieval weight scoring.
POST
/api/v1/recall/test
Diagnostic recall trace returning per-candidate vector, heat, recency, and graph score breakdowns.
POST
/api/v1/feedback
Submit explicit recall relevance feedback (relevant | irrelevant | outdated) to tune salience.
GET
/api/v1/analytics/recall
Retrieve recall hit rates, average similarity, and namespace retrieval analytics.

Knowledge Graph

Knowledge graph neighbor traversal, semantic edge creation, point-in-time temporal validity queries, and contradiction resolution.

MethodEndpointPurpose
GET
/api/v1/agent/graph/status
Inspect knowledge graph vertex and edge counts and Apache AGE sulcus_graph sync status.
GET
/api/v1/agent/graph/neighbors/:id
Traverse outbound and inbound edges around a memory UUID.
POST
/api/v1/agent/graph/relate
Create a weighted semantic edge via relation (related_to, depends_on, contradicts, supersedes, consolidated_from; alias: relation_type).
POST
/api/v1/agent/graph/temporal
Query facts and graph edges for topic valid at ISO-8601 at_time (aliases: query, as_of).
GET
/api/v1/agent/graph/verify/:id
Verify graph parity between PostgreSQL golden_index and graph edges.
GET
/api/v1/agent/graph/snapshot
Export visual graph topology for Memory Constellation rendering.
GET
/api/v1/agent/conflicts
List detected semantic contradictions from the conflicts table across stored memories.
PATCH
/api/v1/agent/conflicts/:id
Resolve a memory contradiction (keep_new, keep_old, keep_both, dismiss).

Synapse Curation

Unified System 1 VCR gating and routing (legacy curation paths remain mounted as backward-compatible aliases), swappable open-weight cartridges, Dynamic Skills VMMU, folder ingestion, and episode synthesis.

MethodEndpointPurpose
POST
/api/v1/vcr/classify
Evaluate candidate text through System 1 VCR returning quality ("store" | "reject") and memory_type.
POST
/api/v1/vcr/label
Submit an operator or agent ground-truth quality and archetype label for System 1 VCR.
POST
/api/v1/vcr/signal
Record an operator or agent labeling signal (quality: "store" | "reject" or memory_type correction).
GET
/api/v1/vcr/signals
List accumulated System 1 VCR training signals for the tenant or namespace.
GET
/api/v1/vcr/status
Inspect active System 1 VCR model metadata, accuracy scores, retrieval weights, and signal counts.
POST
/api/v1/vcr/retrain
Retrain System 1 VCR weights behind the validation promotion gate.
PUT
/api/v1/vcr/models
Sync or reset (DELETE) tenant or namespace System 1 VCR model weights.
POST
/api/v1/decision
Full System 1 VCR evaluation returning store/reject decision and calibrated class probabilities.
GET
/api/v1/models/cartridges
List built-in and imported open-weight embedder, classifier, and Needle Edge SLM cartridges.
POST
/api/v1/models/cartridges
Activate, import, or reset open-weight model cartridges.
POST
/api/v1/train/classifierLocal Engine
Train or auto-scaffold a custom System 1 VCR classifier on a local document folder.
GET
/api/v1/skills
List Dynamic Skills VMMU Map pointers indexed in skills_index.
POST
/api/v1/skills
Ingest a Markdown skill playbook into compact Map pointers and on-demand Territory sections.
POST
/api/v1/skills/fault
Page in a specific skill section Territory on demand and reinforce skill heat.
POST
/api/v1/ingest/folderLocal Engine
Ingest PDF, Markdown, HTML, code, and text documents into document_chunks and memory nodes.
GET
/api/v1/ingest/chunksLocal Engine
Query indexed verbatim document chunks for a namespace.
POST
/api/v1/agent/fold
Fold related memories into a named context cluster.
GET
/api/v1/agent/consolidation-candidates
Preview cold or redundant episodic clusters eligible for synthesis.
POST
/api/v1/agent/consolidate
Distill candidate episodic clusters into high-salience synthesis nodes.
GET
/api/v1/agent/archive
List cold-archived memories eligible for restoration.
POST
/api/v1/agent/restore
Restore archived memory UUIDs back into active working memory.

Namespace Governance

Persistent cross-repo namespace links, per-namespace compression profiles, and Two-Gate Namespace ACL policies.

MethodEndpointPurpose
GET
/api/v1/agent/namespaces
List ACL-readable namespaces and node counts.
GET
/api/v1/namespaces/links
List persistent linked namespaces (?namespace=<primary>).
POST
/api/v1/namespaces/links
Upsert a persistent namespace link (mode: auto_search | on_match).
DELETE
/api/v1/namespaces/links/:primary/:linked
Delete a persistent namespace link (use _all_ or * for tenant-wide primary).
GET
/api/v1/namespaces/profiles
Inspect per-namespace Caveman compression intensity, AST rules, and cartridge bindings.
PUT
/api/v1/namespaces/profiles
Upsert a custom compression and indexing profile for a namespace.
GET
/api/v1/namespaces/acl
Fetch default_policy, explicit ACL rules, and namespace inventory.
POST
/api/v1/namespaces/acl
Upsert an (agent_label, namespace, policy) rule supporting prefix* wildcards.
DELETE
/api/v1/namespaces/acl/:id
Remove an explicit ACL rule by numeric ID.
PUT
/api/v1/namespaces/default
Update tenant-wide default cross-namespace policy (allow | read | deny).

Agent Event Bus

Live multi-agent presence, collision/overlap alerts, fan-out broadcasts, and SSE event replay.

MethodEndpointPurpose
GET
/api/v1/agent/bus/status
Snapshot active_agents, active_peers, territory_conflicts, intent_overlaps, and recent_events.
POST
/api/v1/agent/bus/heartbeat
Upsert session presence (working | idle | compacting | offline), current_intent, and files_touched.
POST
/api/v1/agent/bus/broadcast
Publish a coordination event to source namespace, comma-separated target_namespace, or "all".
GET
/api/v1/agent/bus/stream
SSE stream with Last-Event-ID / ?since_id cursor replay and 15s keepalive.
GET
/api/v1/agent/bus/subscriptions
List active namespace subscriptions and discover ACL-readable workspaces.
POST
/api/v1/agent/bus/subscriptions
Subscribe, unsubscribe, or set watched namespaces (up to 25 per session).

Reactive Triggers

Deterministic event-driven automation across 10 memory, graph, and bus events.

MethodEndpointPurpose
GET
/api/v1/triggers
List configured reactive triggers.
POST
/api/v1/triggers
Create a reactive trigger on any of the 10 supported events.
PATCH
/api/v1/triggers/:id
Toggle enabled or update trigger filters, cooldowns, and action_config.
DELETE
/api/v1/triggers/:id
Delete a trigger by UUID.
GET
/api/v1/triggers/history
Fetch recent trigger execution history.
POST
/api/v1/triggers/evaluate
Evaluate triggers manually against a test event payload.
POST
/api/v1/triggers/feedback
Record trigger helpfulness or noise precision telemetry.

Activity Ledger

1,000-turn SHA-256 mutation ring buffer and out-of-order surgical rollback.

MethodEndpointPurpose
GET
/api/v1/agent/ledger
List Activity Ledger turns and active retention config.
POST
/api/v1/agent/ledger/record
Record a file, CLI, or MCP mutation with SHA-256 pre/post snapshots.
POST
/api/v1/agent/ledger/config
Update namespace ledger capacity and snapshot settings.
POST
/api/v1/agent/ledger/undo
Execute LIFO batch rewind or out-of-order surgical hunk undo.

Settings And Keys

Thermodynamic retention tuning, System 1 VCR configuration, and scoped API key lifecycle.

MethodEndpointPurpose
GET
/api/v1/settings/thermo
Inspect tenant ThermoConfig and defaults (alias: GET /api/v1/settings/lifecycle).
PATCH
/api/v1/settings/thermo
Update per-type half_life_secs, half_life_interactions, floors, and resonance.
GET
/api/v1/settings/vcr
Inspect tenant-wide System 1 VCR gating thresholds, auto-retrain cadence, and keyword overrides.
PATCH
/api/v1/settings/vcr
Update tenant-wide System 1 VCR configuration and keyword overrides.
GET
/api/v1/settings/vcr/:namespace
Inspect per-namespace System 1 VCR override configuration and inheritance state.
PATCH
/api/v1/settings/vcr/:namespace
Upsert or clear per-namespace System 1 VCR overrides (DELETE resets to workspace defaults).
GET
/api/v1/system1/settingsLocal Engine
Read workstation System 1 VCR training defaults and active cartridge bindings.
PUT
/api/v1/system1/settingsLocal Engine
Update workstation System 1 VCR training hyperparameters and thresholds.
GET
/api/v1/keys
List active API key prefixes, labels, and optional scoped namespaces (raw secrets never stored).
POST
/api/v1/keys
Mint a new sk-... API key (returned once on creation; stored as SHA-256 digest).
PATCH
/api/v1/keys/:id
Rename or rescope an existing API key.
DELETE
/api/v1/keys/:id
Immediately revoke an API key.

Organization Admin

Organization seats, workstation leases, agent namespace administration, and Enterprise Appliance sign-in.

MethodEndpointPurpose
GET
/api/v1/org
Inspect organization profile, plan tier, named seats, and active workstation leases.
PATCH
/api/v1/org
Update organization display name.
POST
/api/v1/org/invite
Invite a named seat member (or generate an intranet seat invite on appliances).
DELETE
/api/v1/org/members/:user_id
Remove a seat member and revoke bound workstation leases.
GET
/api/v1/admin/agents
List agent namespaces with memory, heat, and activity summaries.
GET
/api/v1/admin/agents/:namespace
Detailed profile and telemetry for a specific agent namespace.
PATCH
/api/v1/admin/agents/:namespace/status
Pause or resume an agent namespace.
POST
/api/v1/admin/agents/merge
Merge memories and edges from a source namespace into a destination namespace.
DELETE
/api/v1/admin/agents/:namespace
Purge an agent namespace and its scoped memories.
POST
/api/v1/onprem/login
Connected Private VPC seat sign-in (accepts federated OIDC JWT or seat credentials).
POST
/api/v1/airgap/login
Air-gapped intranet seat login returning HS256 session JWT.
MCP Protocol

Canonical MCP Tools

Sulcus implements JSON-RPC 2.0 MCP over Workstation Proxy Stdio (sulcus mcp-proxy), Local Embedded Stdio (sulcus stdio), Streamable HTTP (POST / GET / DELETE /mcp), and Legacy SSE (GET /api/v1/mcp/sse + POST /api/v1/mcp/message).

jsonMCP Transport Configs
// Zero-secret workstation MCP configuration (written automatically by sulcus connect)
{
  "mcpServers": {
    "sulcus": {
      "command": "sulcus",
      "args": ["mcp-proxy"]
    }
  }
}

// Direct Streamable HTTP MCP transport (for cloud-hosted agents without local CLI)
{
  "mcpServers": {
    "sulcus": {
      "url": "https://api.sulcus.ca/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer sk-..."
      }
    }
  }
}

Memory Lifecycle Tools

ToolPurpose
store_memorySave durable knowledge with optional memory_type, label, pointer_summary, is_pinned, namespace, and tags (aliases on tools/call: record_memory, commit_memory, commit_code, remember).
search_memoryHybrid semantic + BM25 + graph resonance recall across primary, global, and linked namespaces, with tier ("hot" | "cold" | "all"), tags, and temporal filters.
expand_memoryExpand full raw Territory (or optional lines="1-80" slice) by memory UUID or ccr:<hex> handle and reinforce current_heat by +0.15 (aliases: page_in, fetch_memory, get_node).
update_memoryUpdate content, pointer_summary, memory_type (reclassify), or is_pinned, or adjust salience via action ("boost" | "deprecate") (aliases: memory_boost, memory_deprecate, memory_reclassify).
forget_memoryDelete an obsolete memory node and optionally purge cold decayed entries via purge_cold=true (aliases: delete_memory, forget).
relate_memoriesCreate a weighted graph edge between source_id and target_id (bidirectional by default; alias: memory_relate).

Context And Skills

ToolPurpose
build_contextConstruct a token-budgeted <sulcus_context> XML block combining pinned mandates and query-relevant memories (prompt, namespace, token_budget, max_nodes).
list_memoriesReturn top active working-set nodes sorted by current_heat with optional namespace and memory_type filters (alias: list_hot_nodes).
list_namespacesList ACL-readable namespaces and active memory counts for the caller.
use_skillList, search, load (action="load"), or ingest procedural playbooks in the Dynamic Skills VMMU on demand (alias: fault_skill).
reduce_outputDeterministically compress noisy CLI logs (command + output) or heavy JSON/diff payloads (output alone) by 80-95% behind a reversible handle for expand_memory.

Local Code AST

ToolPurpose
project_mapBuild or query the local Tree-sitter AST workspace atlas (modules/crates, entrypoints, symbol counts, and CCR handles via sulcus or sulcus mcp-proxy).
find_symbolLocate functions, methods, structs, traits, classes, or types across the workspace with exact [Lstart-Lend] spans.
get_outlineParse a workspace file (path) or inline snippet (content) into syntactic signatures, spans, docstrings, imports, and call edges (alias: outline_code).
get_referencesTrace cross-file symbol definitions, callers, and module importers across the workspace.

Governance And Triggers

ToolPurpose
create_trigger / list_triggers / update_trigger / delete_triggerFull CRUD for deterministic Reactive Memory Triggers; pass include_history=true to list_triggers for recent firing logs.
list_activity_ledger / undo_activityInspect recorded file and CLI mutations and execute selective Surgical Rewind while preserving later non-overlapping edits.
agent_bus_status / manage_namespace_connectionsEnterprise Event Bus tools: inspect active peer agents, territory conflicts, intent overlaps, and persistent namespace links.
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.