Docs
Home GitHub npm

Trust Kernel

Staged memory promotion, three gates, and a full audit trail. SaveState is the only AI memory layer with a state machine instead of a black box.

🛡 Every memory in SaveState starts life as a candidate. It only becomes stable after passing evaluation. Every transition is recorded with a reason and an actor. That is what governance looks like.

What is the Trust Kernel

Most "AI memory" products store whatever the model decides to write, surface it back on the next call, and call it a day. SaveState's Trust Kernel sits in between. It is a small, deterministic engine that:

States

Every entry in the trust store has a state. Only some transitions are allowed.

StateMeaningAllowed transitions
candidateThe default landing state for every accepted write. Visible to debug surfaces, not yet trusted for retrieval in enforce mode.→ stable, rejected, quarantined
stablePromoted by the worker after the entry has passed the configured promotion rule (minimum confidence, minimum age, required tags). Returned by TrustGate in all modes.→ revoked, quarantined
rejectedTerminal. The WriteGate refused the entry — usually because it matched a denylist pattern or fell below the minimum confidence threshold. The content never hits the underlying memory database.none (terminal)
quarantinedHeld aside for human or automated review. Retained for auditing but excluded from retrieval.→ stable, revoked
revokedTerminal. The entry was promoted at one point and has since been retracted. The pattern is added to the denylist so re-writes are blocked at the WriteGate.none (terminal)

Scopes

Every entry also has a scope. Scope determines how the entry can be used and how it ages.

ScopeMeaning
semanticStable facts. "The user prefers TypeScript strict mode." Eligible for promotion to stable and indefinite retention.
proceduralWorkflow patterns and how-to. "When deploying, always run the type check first." Eligible for promotion; useful for the ActionGate's stable_facts trust level.
episodicTime-bound, context-specific. "Today the user is debugging the auth migration." TTL-bound, never promoted to stable, drops out automatically when expiresAt passes.

The three gates

The kernel exposes its enforcement points as small, composable classes you can wire into any storage layer.

⚡ The three modes — shadow, enforce_query, enforce_action — let you stage rollout. Run in shadow first, watch the would-block logs, then flip to enforce when you trust the rules. No big-bang flag day.

CLI usage

Two read-only commands surface the kernel's state and audit trail.

savestate trust status

Snapshot of the trust store: entries by state, entries by scope, last-hour activity, denylist size.

$ savestate trust status

🛡  Trust Kernel

  Entries by state:
    candidate    14
    stable       208
    rejected     6
    quarantined  0
    revoked      2

  Entries by scope:
    semantic     180
    procedural   42
    episodic     8

  Last hour:
  Promotions       3
  Rejections       1

  Denylist size    7

Pass --json for machine output (suitable for cron + alerting):

$ savestate trust status --json
{
  "entriesByState": { "candidate": 14, "stable": 208, "rejected": 6, "quarantined": 0, "revoked": 2 },
  "entriesByScope": { "semantic": 180, "procedural": 42, "episodic": 8 },
  "promotionsLastHour": 3,
  "rejectionsLastHour": 1,
  "denylistSize": 7,
  ...
}

savestate trust audit

The audit trail. Every state transition that has ever happened, most recent first.

$ savestate trust audit --limit 5

🧾 Trust Audit  (last 5)

  2026-04-28 14:02:11  candidate → stable      (promotion-worker)
    id: 8e3a4b9c-1a2f-4f6e-9d1e-2c7b1d4a55b8
    reason: confidence 0.92 ≥ 0.8 and age 21m ≥ 10m

  2026-04-28 13:58:02  candidate → rejected    (write-gate)
    id: a91b3322-77af-4f0d-b3e5-19c8d6b0ee71
    reason: Denylisted: matches secret-pattern rule "api-key-prefix"

  2026-04-28 13:51:44  stable → revoked        (operator:david)
    id: 6f0e1a55-2d13-4b8f-ab44-8a9e1c2d3f10
    reason: User requested removal; pattern added to denylist

  2026-04-28 13:40:20  candidate → stable      (promotion-worker)
    id: 4d2c8f01-8e9a-4a1b-8e44-1f6c7e9d3aa2
    reason: confidence 0.88 ≥ 0.8 and age 12m ≥ 10m

  2026-04-28 13:32:09  candidate → quarantined (action-gate)
    id: c4f2b1d9-9c01-4f12-9e3d-7e9b8f1a23c6
    reason: Held for review: low-confidence tag "external-claim"

Flags: --limit n (default 50), --json for raw events.

Programmatic usage

Wiring a WriteGate into the MemoryStore is the supported path for surfacing rejections back to the caller. Rejected writes raise TrustGateRejection; the error carries the gate's blockers list so you can show the user exactly why the write was refused.

import { MemoryStore, TrustGateRejection } from '@savestate/cli';
import { TrustStore, WriteGate } from '@savestate/cli';

const trustStore = new TrustStore();
const writeGate = new WriteGate({ store: trustStore, minConfidence: 0.5 });

const memory = new MemoryStore({ writeGate });

try {
  await memory.create({
    type: 'semantic',
    content: 'User prefers TypeScript strict mode',
    importance: 0.9,
  });
} catch (err) {
  if (err instanceof TrustGateRejection) {
    // err.blockers is a string[] of human-readable reasons.
    console.error('Trust Kernel refused this write:', err.blockers);
  } else {
    throw err;
  }
}

Why this matters

🔐 Every other AI memory product is a black box. ChatGPT Memory, Claude Projects, Mem.ai, Letta — none of them ship a state machine, an audit log, or a deny-by-default action gate. SaveState does. If you are a compliance team, this is the layer you have been waiting for.

Roadmap

Phases 1 and 2 (state machine, three gates, audit trail, CLI surfaces, MemoryStore integration) shipped in April 2026. Phase 3 is in progress and covers:

Next steps