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.

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=agent for your own agent_id → trust ≥ 1 (self-author).
scope=agent targeting another agent, scope=fleet, or scope=tenant → trust ≥ 2 (the same cross-agent governance bar used by memclaw_list / memclaw_stats / memclaw_evolve / memclaw_insights with scope=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
`memclaw_keystones`	(read-only)	≥ 0	List scope-merged keystone rules. Call once per session.
`memclaw_keystones_set`	`set`	≥ 1 (self) / ≥ 2 (other)	Upsert a keystone by `doc_id`.
`memclaw_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

memclaw_keystones and GET /api/v1/memclaw/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 memclaw_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/memclaw/keystones prefix:

GET /api/v1/memclaw/keystones — list (open).
POST /api/v1/memclaw/keystones — upsert (dynamic trust).
DELETE /api/v1/memclaw/keystones/{doc_id} — delete (dynamic trust).

See the keystones API reference for the rendered schemas.

How keystones relate to other governance

Keystones are complementary to the rest of MemClaw'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"

Keystones