Coordination & Governance

Namespaces, Linking & Two-Gate ACL

Isolate memory per repository by default, bridge multi-repo architectures with Persistent Linked Namespaces, and enforce least-privilege access across agents using Two-Gate Namespace ACLs.

Persistent LinksTwo-Gate ACLPrefix* Wildcards404 Existence Masking

01 · Isolation Boundaries

How Sulcus Resolves Namespaces

Every memory node, trigger, ledger entry, and bus event belongs to a sanitized namespace slug within your tenant.

1. Explicit Override

Request or Env Scope

Per-call namespace arguments, X-Namespace headers, sulcus mcp-proxy --namespace, or SULCUS_NAMESPACE take top priority.

2. Workstation Config & Repo Slug

Auto-Detected Repo Scope

IDE and CLI plugins derive a deterministic namespace from your Git repository name (for example checkout-web or payments-rails), falling back to namespace in sulcus.ini or default.

3. Shared Global Layer

The "global" Namespace

Memories stored in global hold organization-wide engineering mandates and standing preferences that apply across every workspace.

02 · Cross-Repository Recall

Persistent Linked Namespaces

Modern systems span multiple repositories: a frontend repo calling a Rails billing service, or microservices sharing a platform protobuf repo. Linked Namespaces let you connect related workspaces once so recall spans them automatically.

mode: "auto_search"0.92x Salience Weight

Includes the linked namespace in every default recall and hot-context query from the primary workspace. Best for foundational platform contracts, authentication libraries, and security runbooks that apply on every turn.

mode: "on_match"Domain-Triggered

Activates only when the user prompt or search query matches the linked namespace slug, its display_label, or any meaningful domain keyword in its description (generic words like repo, service, or api are filtered out so unrelated prompts stay clean).

bashWorkstation CLI (sulcus namespace)

# List active namespace links visible to your workstation
sulcus namespace list

# Always include shared-platform architecture in recall across every repo (*)
sulcus namespace link shared-platform --all --mode auto_search \
  --label "Platform Architecture" \
  --desc "OIDC JWT middleware, gRPC contracts, shared schema invariants"

# Conditionally pull payments-rails memories into checkout-web only when prompts match
sulcus namespace link payments-rails --primary checkout-web --mode on_match \
  --label "Payments Rails Service" \
  --desc "Stripe webhooks, idempotency keys, settlement ledger, refunds"

# Remove a persistent link
sulcus namespace unlink payments-rails --primary checkout-web

bashREST API (POST /api/v1/namespaces/links)

# Upsert a persistent namespace link via REST
curl -X POST https://api.sulcus.ca/api/v1/namespaces/links \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_namespace": "checkout-web",
    "linked_namespace": "payments-rails",
    "mode": "on_match",
    "display_label": "Payments Rails Service",
    "description": "Stripe webhooks, idempotency keys, settlement ledger, refunds"
  }'

MCP System Instructions (<sulcus-namespaces>)

When an agent connects over MCP, Sulcus injects an ACL-filtered <sulcus-namespaces> block into the MCP initialize instructions so the model knows which peer repositories are linked and can target them explicitly when needed:

xmlInjected during MCP initialize

<sulcus-namespaces primary="checkout-web">
  <linked namespace="shared-platform" mode="auto_search" label="Platform Architecture">
    OIDC JWT middleware, gRPC contracts, shared schema invariants
  </linked>
  <linked namespace="payments-rails" mode="on_match" label="Payments Rails Service">
    Stripe webhooks, idempotency keys, settlement ledger, refunds
  </linked>
</sulcus-namespaces>

03 · Zero-Trust Multi-Agent Governance

Two-Gate Namespace ACL

Sulcus enforces two independent authorization gates on every cross-namespace operation so teams can share verified engineering knowledge without leaking raw session chatter or granting unintended write access.

Sulcus Control Panel showing Tenant Default Namespace Policy and Effective Agent x Namespace Permission Matrix — Interactive Agent x Namespace matrix in the Control Panel. Operators can set the tenant default policy (allow, read, or deny), click any matrix cell to cycle overrides, or define prefix* wildcard rules such as ci-* -> prod-* (deny).

Gate 1 · Namespace Policy Gate

Read / Write / Deny Enforcement

allow: Full read and write access (memories, graph edges, triggers, bus broadcasts, and ledger).
read: Read-only recall, graph traversal, and bus subscription. Any write attempt returns 403 Forbidden.
deny: Zero access. Cross-namespace reads and subscriptions return 404 Not Found rather than 403so unauthorized agents can't probe whether a namespace exists.

Gate 2 · Archetype Privacy Gate

Curated Knowledge vs. Raw Episodes

During unlinked peer discovery and wildcard prefix searches (such as namespace: "eng-*"), Gate 2 restricts cross-namespace results to durable archetypes: fact, procedural, preference, semantic, and synthesis. Raw episodic session turns are never exposed across unlinked peer discovery, even when pinned. Explicitly linked namespaces bypass Gate 2 because an administrator intentionally paired those workspaces.

Self-Escalation Protection on Scoped Agent Keys

API keys minted with a bound Scoped Namespace cannot modify ACL rules, change the tenant default policy, or create tenant-wide (*) namespace links. Calls to POST /api/v1/namespaces/acl, DELETE /api/v1/namespaces/acl/:id, and PUT /api/v1/namespaces/default with an agent-scoped key always return 403 Forbidden.

ACL Specificity & Evaluation Order

Order	Matching Rule	Result	Behavior
#0	Unscoped Org Key or Human OIDC Session	allow (full tenant read + write)	Organization-level keys without a bound namespace and human Studio/Control Panel sessions can administer all tenant namespaces.
#1	Exact (agent_label, namespace) Rule	Explicit rule policy	Highest specificity override for an exact agent slug and exact target namespace.
#2	Agent Own Namespace	allow	An agent always retains read/write access to its own bound namespace unless explicitly overridden at Rank 1.
#3	Exact agent_label + Prefix/Wildcard Namespace	Longest prefix wins	Matches rules such as payments-rails -> prod-* before payments-rails -> *.
#4	Prefix/Wildcard agent_label + Target Namespace	Ranked by (agent_spec, ns_spec)	Matches team or CI patterns such as ci-* -> prod-* or eng-* -> shared-*.
#5	Implicit "global" Read Fallback	read (when default_policy is deny)	The tenant "global" namespace stays readable for organization-wide conventions unless explicitly denied.
#6	Tenant Default Policy	allow \| read \| deny	Configured via PUT /api/v1/namespaces/default (defaults to "allow" on new tenants).

bashConfiguring Default Policy & Wildcard ACL Rules

# 1. Set tenant-wide default cross-namespace policy ("allow" | "read" | "deny")
curl -X PUT https://api.sulcus.ca/api/v1/namespaces/default \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_policy": "read"}'

# 2. Block all CI runner keys (ci-*) from reading or writing production namespaces (prod-*)
curl -X POST https://api.sulcus.ca/api/v1/namespaces/acl \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_label": "ci-*",
    "namespace": "prod-*",
    "policy": "deny"
  }'

# 3. Grant payments-rails read + write access to shared-platform
curl -X POST https://api.sulcus.ca/api/v1/namespaces/acl \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_label": "payments-rails",
    "namespace": "shared-platform",
    "policy": "allow"
  }'

04 · Protocol Reference

Namespace & ACL Endpoints

GET/api/v1/agent/namespaces

List all ACL-readable namespaces and memory counts for the caller.

GET/api/v1/namespaces/links

List persistent linked namespaces (supports ?namespace=<primary>).

POST/api/v1/namespaces/links

Create or update a persistent namespace link (auto_search or on_match).

DELETE/api/v1/namespaces/links/:primary/:linked

Remove a link (use _all_ or * for tenant-wide primary links).

GET/api/v1/namespaces/acl

Inspect default policy, explicit ACL rules, and namespace inventory.

POST/api/v1/namespaces/acl

Upsert an agent_label -> namespace rule (allow, read, or deny; supports prefix*).

DELETE/api/v1/namespaces/acl/:id

Delete an explicit ACL rule by numeric ID.

PUT/api/v1/namespaces/default

Set tenant-wide fallback policy (allow, read, or deny).

Explore Agent Bus Full REST & MCP API