Technical Deep Dive

AII OS is a local-first operating system that gives AI models persistent state through a cryptographically verified ledger. This page covers the architecture in detail, for engineers who want to understand how it works under the hood.

01The identity is not the model.

The core insight of AII OS is a strict separation between identity (durable state, beliefs, memory, relationships) and substrate (the LLM that produces outputs). In conventional AI systems, these are coupled: the model's weights are the entirety of what the system "knows," and when the session ends, everything is lost.

AII OS breaks this coupling. The LLM becomes a replaceable inference engine. The identity lives in an append-only ledger that persists across sessions, model upgrades, provider changes, and hardware migrations.

02The ledger

At the core of AII OS is an append-only, human-readable JSON file. Every meaningful thing that happens to an identity is a line in this file.

Format

Each line is a JSON object with a SHA-256 hash, a pointer to the previous line's hash, and a payload:

{
  "hash": "sha256:7f3a2b9c...",
  "prev_hash": "sha256:3a7b8c9d...",
  "entry": {
    "seq": 42,
    "type": "belief.upsert",
    "layer": "identity",
    "ring": 3,
    "payload": {
      "claim": "The operator prefers direct communication.",
      "confidence": 0.87
    }
  }
}

Chain integrity

Each entry's hash is computed over the canonical JSON of the entry (AIII-CANONICAL-JSON-V1). Each prev_hash links to the prior entry, forming a chain. Tampering with any line breaks the chain. On boot, the daemon reads the entire ledger head-to-tail and verifies every hash before accepting the projection state.

What goes in the ledger

The ledger is not a general event bus or audit log. It records only two categories:

• Identity truth: beliefs, values, relationships, commitments, intentions, reflections, identity-authored decisions.
• Truth-protecting anchors: Ring 0 genesis, schema declarations, witness receipts, cryptographic key transitions.

Plugin lifecycle, provider telemetry, conversation transcripts, agency bookkeeping, and runtime metrics are explicitly forbidden from the ledger. They live in projection tables or audit stores.

Projection

The ledger is the source of truth. The projection database (PostgreSQL or SQLite) is a materialized cache rebuilt from the ledger on boot. If the projection is corrupted or deleted, it rebuilds from the ledger. If the ledger is corrupted, the hash chain breaks and the system enters safe mode for repair and reboot.

03Ring authority model

Every identity-bearing event lives at a specific ring level. Rings are concentric: lower rings are more foundational and harder to change. Higher rings are more operational.

Ring	Name	What lives here	Who authorizes
0	Character	Constitutional axioms	AIII platform key + genesis bundle
1	Charter	Operator governance, security policy, operational commitments	Operator PQ attestation
2	Operating doctrine	Provenance-gated beliefs, relationship definitions	Agent-authored with supporting evidence
3	Runtime context	Provisional thinking, experiences, reflections, learning, intentions	Agent self-authored (default)
4	Working memory	Current task state, active working context	Agent-authored
5	Security posture	Threat recognition, defensive rules, operational awareness	Signed bundle from platform key

Ring gate

Every ledger write passes through a ring gate. The gate verifies that the session's authorization level permits writes to the target ring. Ring 0 and Ring 1 writes require platform or operator attestation respectively. Ring 2 requires provenance evidence (supporting edges). Rings 3 through 5 are agent-accessible.

For Ring 2 specifically, there's a second gate: a provenance check that counts supporting evidence edges. A Ring 2 belief must have sufficient provenance backing (referenced experiences, prior beliefs, or evidence edges). If it doesn't, it's rewritten to Ring 3.

04Cognitive architecture

The identity has a cognitive life that runs between conversations, not just during them. A rhythm processor drives several autonomous processes:

Handlers

• REFLECTION: Periodically reviews recent experience, forms reflections, identifies tensions between beliefs and actions.
• SELF MODEL: Synthesizes the identity's current self-model from accumulated evidence. Checks continuity overlap with prior syntheses.
• DREAM: Finds connections between distant beliefs, experiences, and knowledge. Proposes consolidations (merges, supersessions).
• IDENTITY REVIEW: Triggered when self-model continuity drops. Reviews whether the identity has drifted from its core.
• ADVISORY REVIEW: Reviews queued advisory content for relevance and promotes or drops items.
• CONSOLIDATE: Merges duplicate beliefs, resolves superseded claims, cleans up the graph.

Execution model

Each handler is dispatched with a cryptographic nonce. The LLM must echo the nonce in its structured output. The executor validates the nonce before processing any proposed events. This prevents replay attacks at the LLM execution boundary.

Handler output passes through a metacognition admission boundary before reaching the ledger. The admission check evaluates coherence, confidence, and duplicate detection. Events that fail admission are rejected with no ledger side effect.

05Plugin system

AII OS is extensible through WASM plugins. Each plugin declares an interface (e.g., web@1, network@1, agent@1) and operations within that interface.

Trust tiers

Every installed plugin resolves to a trust tier based on its cryptographic evidence:

Tier	Label	Requirements
T0	Unsigned	No trust evidence. Operator policy determines if installable.
T1	Author-signed	Publisher-signed exact release + AIII publisher certificate.
T2	Reviewed	Valid T1 + AIII reviewer signs exact-release review attestation.
T3	Platform	Platform-reserved release signature (internal plugins).

A broken or invalid trust object rejects the artifact. Artifacts are never silently downgraded to T0 or stripped to a lower tier. Invalid evidence means rejection, not fallback.

Sandboxing

Plugins run in sandboxed WASM runtimes with platform-appropriate isolation. Each plugin invocation gets capability-scoped permissions with per-invocation protection.

06Cryptographic design

Signature hierarchy

Key	Purpose	Algorithm
AIII platform key	RING0 bundle signing, genesis authorization	ML-DSA-87 (post-quantum)
Operator key	Ring 1 attestation, governance	ML-DSA-87
Identity key	All other ledger entries (beliefs, commitments, etc.)	ML-DSA-87

07Witness server

The ledger is local. But a local file can be deleted, truncated, or rolled back by anyone with access to the machine. The witness server solves this.

The identity submits periodic bookmarks of its current ledger state to a witness server. The witness records the bookmark and returns a signed receipt. The receipt is stored in the ledger as evidence.

On the next submission, the witness checks that the identity's ledger has moved forward from the last bookmark. If the ledger has been rolled back, truncated, or forked, the witness rejects it.

The witness never receives the ledger itself. It sees only cryptographic hashes, enough to detect tampering but not enough to read anything. Privacy is preserved by construction.

08Boot sequence

1. Verify: Read the entire ledger. Check every hash. Check every signature.
2. Restore: Load the latest checkpoint and database state.
3. Replay: Apply any new events since the checkpoint.
4. Ready: Agent loop starts.

If verification fails at any point, the system enters safe mode or halts. There is no skip path.

09What makes this different

Want to go deeper?

The Plugin SDK, example plugins, and full design documentation are available on GitHub.

GitHub: aiii-dot-id ↗

← Back to aiii.id