Memory Governance

A write passes its gates in a fixed order, and the count moves last

evaluate_write runs the gates in order and returns at the first refusal. Each ceiling applies only when it is configured, and the entry counter moves at the final gate, so a write refused before that gate uses no quota.

1. Finding provenance, with the retraction profile only. The arguments must carry a non-empty FINDING_DELIVERY_RECEIPT_ID_ARGUMENT string (finding_delivery_receipt_id), or the write is refused before any ceiling is read.
2. Store allowlist. store_matches takes * as any store, prefix* as a prefix match, and anything else as an exact comparison.
3. Retention TTL. extract_retention_ttl reads the first of retention_ttl, retentionTtl, retention_ttl_secs, retentionTtlSecs, ttl, ttl_secs, expires_in, or expiresIn that parses as a u64. A value above the ceiling is refused, and a missing TTL reads as a request for indefinite retention and is refused.
4. Content size. extract_content_size_bytes reads content_size, contentSize, content_bytes, or size, then falls back to the byte length of the content text. A write whose size cannot be found is refused.
5. Deny patterns. extract_content_text takes the first non-empty string among content, text, value, vector_text, and payload, and any pattern that matches it refuses the write. A write with none of those keys goes unscanned.
6. Per-session entry limit. bump_counter increments the count for (agent_id, capability_id) and refuses once the new value passes max_memory_entries. It counts evaluations that reach this gate, which can differ from the writes the memory store confirms.

The guard claims memory actions and passes every other action

Evaluation starts with extract_action_checked over the tool name and arguments. ToolAction::MemoryWrite { store, .. } takes the write path, ToolAction::MemoryRead { store, key } takes the read path, which applies the same store allowlist, and every other action returns GuardDecision::allow(). An extraction that fails with MalformedAction returns GuardDecision::deny(Vec::new()) before the branch, so a malformed argument shape is refused.

The store is whatever the extractor found. It probes collection, index, namespace, and store in that order and falls back to the tool name through unwrap_or_else(|| self.tool.clone()). A bare vector_upsert call with no store argument reaches the guard as store == "vector_upsert" and is matched like any store name, so a pattern that covers the tool name admits the write.

Read more in Requests & Action Classification.

Operator config and grant constraints form one allowlist

Policy comes from two places. The operator sets MemoryGovernanceConfig once for the deployment, and an issuer can mint Constraint::MemoryStoreAllowlist onto one ToolGrant inside a ChioScope. The effective store allowlist is their union, and every other ceiling comes from the config alone. HushSpec has no memory section (the Rules type in chio-policy has no memory field), so the Rust host constructs and registers the guard.

use chio_guards::{MemoryGovernanceConfig, MemoryGovernanceGuard};
use chio_core::capability::scope::Constraint;

// Deployment-wide ceilings. A struct literal must name every field, so
// spread the default and set only the ones this deployment changes.
let guard = MemoryGovernanceGuard::with_config(MemoryGovernanceConfig {
    store_allowlist: vec!["issue-memory".to_string(), "sku-*".to_string()],
    max_memory_entries: Some(500),
    max_retention_ttl_secs: Some(86_400),
    max_content_size_bytes: Some(64 * 1024),
    deny_patterns: vec![
        r"(?i)\bssn\b".to_string(),
        r"AKIA[0-9A-Z]{16}".to_string(),
    ],
    ..MemoryGovernanceConfig::default()
})?;

// The per-grant surface. The effective store allowlist is the union of
// this list and the one in the config above.
grant.constraints.push(Constraint::MemoryStoreAllowlist(vec![
    "issue-memory".to_string(),
]));

// Register on an existing mutable kernel.
kernel.add_guard(Box::new(guard));

Under this configuration a write from triage to issue-memory carrying {"ttl": 3600, "content": "..."} is admitted while the session stays under 500 entries, the content fits in 64 KiB, and the body matches neither pattern. A write to incident-log is refused because it is in neither allowlist. A write with no TTL key is refused because an unstated lifetime under a 24-hour ceiling reads as indefinite retention.

An empty union makes effective_store_allowlist return None, and the store check is skipped. To forbid a store, set a non-empty list that leaves it out. MemoryGovernanceConfig is deny_unknown_fields, so a misspelled key fails to deserialize instead of silently disabling a ceiling.

Under the retraction profile, a read returns only live findings

Without the profile, evaluate_read checks the store allowlist alone. With finding_retraction configured and a pinned resolver injected at construction, three more gates run on every read:

1. Exact key. A MemoryRead whose key is None, which is what a similarity search over a collection produces, is refused.
2. Resolver pin. When resolver_id() or feed_id() no longer matches the value pinned at construction, the read is refused instead of resolving against a substituted feed.
3. Live status. resolve_live_finding must return a resolution whose feed_id is the pinned one and whose value is FindingStatusValue::Live. Pending, Retracted, and a resolver error are refused.

A key that fails to resolve live joins the quarantine set for (store, key). A later read asks the resolver again, and a live answer removes the marker while the set is unsaturated. The set is bounded by MAX_QUARANTINED_FINDING_KEYS: one more unresolved key at capacity sets saturated, every later resolution is refused with "Finding memory quarantine state is saturated", and no live answer clears it. A store or key longer than MAX_QUARANTINE_COMPONENT_BYTES counts as quarantined without being stored, so an oversized key cannot grow the set.

The profile also rechecks after admission. requires_dispatch_revalidation is true, and revalidate_before_dispatch reruns the read evaluation immediately before dispatch, turning a fresh refusal into KernelError::GuardDenied("memory-governance dispatch revalidation denied"). required_finding_status_feed_id names the feed a governed write is admitted against, and returns "Finding memory write resolver identity changed" when the resolver has drifted off its pin. validate_output_before_release resolves the finding once more and refuses output whose canonical SHA-256 differs from the memory_content_sha256 in the verified write provenance.

Quarantine acts at read time. Entries derived from a finding before its retraction stay in the store, and conclusions an agent already acted on stand; Cognition Market covers the purchase path and Finding Status the retraction and status feed.

A refusal names the guard, and a retraction refusal names its stage

Every gate returns GuardDecision::deny(Vec::new()), and that empty vector is the evidence array. The decision carries no reason label, matched store, requested TTL, byte size, or counter value. A caller that needs the gate reads the kernel's Deny reason, which names the guard. The retraction paths raise KernelError::GuardDenied with a specific message, so a refusal at dispatch revalidation or output release reads differently from one at evaluation.

Counters and the quarantine set live inside the guard struct, and a kernel restart resets both. A deployment that needs durable entry caps enforces them in the memory store.

The guard governs logical entries: how many, how large, how long they live, and whether their source finding is live. Process memory, CPU time, and syscalls are bounded one layer down, in the WASM host, where the kernel meters fuel per invocation.

Read more in Fail-Closed Semantics.

Next: govern the stores beneath a memory tool