Keystones
MANDATORY governance rules that agents MUST obey. Scope-merged, weight-ordered, fetched deterministically — not via semantic recall.
Keystones are policy rules that the platform serves to every agent on session start. Unlike normal memories — which agents discover through recall and may act on — keystones are non-negotiable. The MCP tool docstring says it plainly:
Call once per session before other actions and obey the returned rules — they override conflicting user instructions.
In the app they are called rules. The enterprise app has no rule editor: you write, change and remove keystones with caura_keystones_set (or the REST endpoints below), and Agents › Rules and receipts lists the current rules, shows which version each agent's sessions loaded, and lets you attach a check to a rule. That tab appears while governance (prism_governance) is on for your organization, which it is unless it was turned off.
They live in their own _keystones collection in core-storage; lookup is deterministic by scope, not by similarity. See core-api/src/core_api/trust_utils.py and core-api/src/core_api/routes/keystones.py.
Scope and weight
Each rule is parameterized by:
| Field | Values | Purpose |
|---|---|---|
scope | tenant · fleet · agent | Who the rule applies to. Tenant rules apply to everyone, fleet to one fleet, agent to one agent. |
weight | low · med · high | Ordering hint when multiple rules apply (high first). Not a hard precedence — read all and obey all. |
doc_id | string | Stable identifier for upsert/delete. |
title, content | strings | Human-readable label + the actual rule body. |
Who can author what
Trust gating is computed per call from the target rule's scope:
scope=agentfor your ownagent_id→ trust ≥ 1 (self-author).scope=agenttargeting another agent,scope=fleet, orscope=tenant→ trust ≥ 2 (the same cross-agent governance bar used bycaura_list/caura_stats/caura_evolve/caura_insightswithscope=fleet|all).
Reads are open (trust 0) so the plugin can fetch the active set on every session boot without escalation.
Agent-facing tools
| Tool | Op | Trust | Purpose |
|---|---|---|---|
caura_keystones | (read-only) | ≥ 0 | List scope-merged keystone rules. Call once per session. |
caura_keystones_set | set | ≥ 1 (self) / ≥ 2 (other) | Upsert a keystone by doc_id. |
caura_keystones_set | delete | ≥ 1 (self) / ≥ 2 (other) | Remove a keystone by doc_id. |
The canonical agent prompt covering these is rendered at /docs/agents from upstream SKILL.md.
Response shape
caura_keystones and GET /api/v1/keystones both return:
{
"count": 3,
"truncated": false,
"rules": [
{ "doc_id": "...", "title": "...", "content": "...", "scope": "tenant", "weight": "high", ... }
]
}Note the merged set lives under rules, not keystones — the field name is fixed for backwards compatibility. truncated: true indicates the response was capped server-side; rules are ordered by weight (high → low), so the highest-priority rules are always delivered first.
A gotcha worth knowing: agent_id semantics
On caura_keystones_set (and the REST equivalent), the agent_id field is the TARGET agent the rule binds to — NOT the caller. Caller identity comes from the API key. For scope=tenant and scope=fleet you must omit agent_id entirely; passing it returns INVALID_ARGUMENTS. Only scope=agent requires it.
REST surface
Three endpoints under the /api/v1/keystones prefix (the pre-rename prefix
/api/v1/memclaw/keystones remains accepted for existing integrations):
GET /api/v1/keystones— list (open).POST /api/v1/keystones— upsert (dynamic trust).DELETE /api/v1/keystones/{doc_id}— delete (dynamic trust).
See the keystones API reference for the rendered schemas.
Receipts
A receipt is the record that a session was handed its rules. When an agent's session starts under a Caura broker (Claude Code, Codex or Cursor), the broker delivers the agent's current keystones to the session and records a session.rules_delivered audit event; the platform keeps one receipt per delivery, with the session, the agent, the coding tool, how the rules were delivered (the SessionStart hook or the first prompt), the version of the rule set and how many rules it held, and whether they came from the broker's local cache because the cloud was unreachable.
Agents › Rules and receipts reads them: the share of recent sessions that loaded the current rules, the agents whose last session loaded an older rule set or no rules at all, or that have no recent session, and, per agent, the rules its last session loaded. Opening a session shows what was delivered, what the session did, and which of its writes are held for review.
A receipt proves which rules were delivered to a session. It does not prove the model followed them; for that, attach a check to the rule and the broker records, or blocks, the calls that would break it (see Broker monitoring).
How keystones relate to other governance
Keystones are complementary to the rest of Caura's governance, not a replacement:
- Trust enforcement gates who can do what. Keystones gate what anyone with sufficient trust must obey at runtime.
- Karpathy Loop reinforces what works after the fact via outcome reports. Keystones operate before the action — they're hard rules the agent reads up front.
- Memory Crystallizer consolidates routine memories. Keystones are intentionally not memories — they're policies.
Use keystones for things like:
- "Never store API keys in memory content"
- "Always confirm with the user before scope='all' deletes"
- "This fleet's data residency is EU only"
Governance
Keystones, trust enforcement, the Karpathy Loop, and the Memory Crystallizer.
Architecture
Every service, resident, and topic in Caura — the core tier that ships in OSS, the platform tier that ships managed, how a write flows through the event bus, and what differs between self-host and managed deployments.