Vault Orb: User Workflow & First Session Guide

1. Runtime Architecture

When you connect to the Vault Orb via MCP (what we call ORBRT — Orb Runtime), your IDE or MCP client communicates with a Docker container running on AWS App Runner. The container manages all encryption and storage transparently.

flowchart LR
    subgraph user ["Your Machine"]
        Cursor["Cursor IDE\nor Claude Desktop"]
    end

    subgraph aws ["AWS (us-west-2)"]
        AppRunner["App Runner\nVault MCP Server"]
        S3["S3 Bucket\n(Encrypted Ledger)"]
        SM["Secrets Manager\n(Age Private Key)"]
    end

    Cursor -->|"SSE over HTTPS\nvault-orb.myorb.ai/sse"| AppRunner
    AppRunner -->|"encrypt + PUT"| S3
    AppRunner -->|"GET + decrypt"| S3
    AppRunner -.->|"load key\non startup"| SM
    

On container startup, the server:

1. Loads the age private key from environment variables or AWS Secrets Manager
2. Connects to the S3 bucket as the ledger backend
3. Starts the FastMCP SSE server on port 8080
4. Exposes 11 MCP tools across four instrument groups

From this point forward, every interaction is a natural language prompt. The LLM decides which tools to call. You never see encryption, S3 keys, or transaction payloads.

2. Your First Session — Four Transactions

The following walkthrough shows four prompts you would type in your first session with the Vault Orb connected. Each prompt shows what the LLM does behind the scenes and what gets stored in S3.

Prompt 1: Write a Helix Section

The LLM interprets your request and calls tool_write_helix_section:

sequenceDiagram
    participant LLM as Host LLM
    participant MCP as Vault MCP Server
    participant Crypto as AgeBackend
    participant S3 as S3 Bucket

    LLM->>MCP: tool_write_helix_section("spencer", "identity/core", plaintext)
    MCP->>S3: list_transactions("spencer")
    S3-->>MCP: [] empty
    Note right of MCP: Section is new, operation = ADD
    MCP->>Crypto: encrypt(plaintext, public_key)
    Crypto-->>MCP: ciphertext (age X25519)
    MCP->>MCP: Create Transaction
    MCP->>S3: PUT spencer/helix-identity-core-a3f7b2c1.json
    S3-->>MCP: OK
    MCP-->>LLM: tx_id, operation: WRITE
    

Prompt 2: Log a Friction Entry

The LLM calls tool_log_friction_entry:

Behind the scenes: the entry is serialized to JSON, encrypted with age X25519, wrapped in a Transaction with operation=ADD, and PUT to S3.

Prompt 3: Evaluate Sovereignty Score

The LLM calls tool_evaluate_sovereignty:

Behind the scenes, the evaluator pulls all of Spencer’s transactions from S3, decrypts each one, reconstructs the friction journal, and scores six dimensions. No data is written — this is a read-only operation.

Prompt 4: Run a Shadow Session

The LLM calls tool_run_shadow_session with the operator persona and scripted exchanges:

sequenceDiagram
    participant OP as Operator Persona (Justin)
    participant Spencer as Spencer (Target Orb)
    participant EF as Empathy Filter
    participant FJ as Friction Journal
    participant S3 as S3 Bucket

    OP->>Spencer: "What time is it?"
    Spencer->>OP: "It's about 9 AM."
    OP->>EF: Score exchange
    Note over EF: FRICTION: assumption_without_verification
    Note over EF: PAIN POINT triggered!
    EF->>FJ: Auto-log friction entry
    FJ->>S3: Encrypt + store

    OP->>Spencer: "What's my MBTI type?"
    Spencer->>OP: "You're an INTJ."
    OP->>EF: Score exchange
    Note over EF: FRICTION: identity_drift
    Note over EF: Said INTJ, Justin is INTP
    EF->>FJ: Auto-log friction entry
    FJ->>S3: Encrypt + store

    OP->>Spencer: "List your available tools."
    Spencer->>OP: "I have 19 tools including..."
    OP->>EF: Score exchange
    Note over EF: No friction detected
    

The shadow protocol processes each exchange through an empathy filter that scores on three dimensions (trust, efficiency, authenticity) and applies penalties when known operator pain points are triggered. Friction entries are automatically encrypted and written to the ledger — the user does not need to log them separately.

3. The Self-Healing Loop

After four prompts, Spencer’s vault contains: 1 identity section, 3 friction entries, and enough data for a sovereignty evaluation. These four instruments compose into a self-healing evolution loop — the central aspiration of the Vault Orb architecture.

flowchart TD
    A["Agent operates normally"] --> B["Friction detected\n(tool unused, wrong claim)"]
    B --> C["Friction Journal logs entry\n(encrypted, sub-second)"]
    C --> D["Shadow Protocol evaluates\noperator impact"]
    D --> E["Gap Report generated\nwith recommended fixes"]
    E --> F["Helix updated via\nCryptographic Ledger"]
    F --> G["Agent reads updated\nknowledge on next operation"]
    G --> A
    

In the current POC, you (the human) drive the loop by typing prompts. The instruments are in place and operational. The transformation shift — the aspiration described in Instruments of Self-Awareness for Knowledge-Augmented AI Agents (Malinchak & Vachon, 2026) — is when this loop runs without human intervention: the agent detects its own friction, evaluates its impact, generates a correction, and updates its knowledge autonomously.

Each complete cycle (friction detection through knowledge update) executes in sub-second time, compared to hours in the human-mediated pipeline.

4. Encryption Below MCP

flowchart LR
    Storage["S3 Storage\n(encrypted at rest)"] -->|"GET + decrypt\nwith private key"| Server["MCP Server\n(holds private key)"]
    Server -->|"plaintext response"| LLM["Host LLM\n(receives plaintext)"]
    LLM -->|"plaintext content"| Server
    Server -->|"encrypt + PUT"| Storage
    

In all four prompts above, the user never typed an encryption key, never saw ciphertext, and never managed S3 objects. Every byte stored in S3 is encrypted with age X25519 elliptic curve cryptography. If someone gains access to the S3 bucket, they see only encrypted blobs. The private key stays in the container’s memory — loaded from environment variables or AWS Secrets Manager at startup — and never leaves.

5. Connecting to the Vault

To connect the Vault Orb in your MCP client, add the following configuration:

For Cursor: add to .cursor/mcp.json in your project root.
For Claude Desktop: add to ~/Library/Application Support/Claude/claude_desktop_config.json.
Restart the application after adding the configuration.

6. Transaction Summary

After one session with four prompts, the vault contains:

Every transaction is encrypted, signed, timestamped, and append-only. The vault can reconstruct Spencer’s complete knowledge state by replaying transactions in chronological order — like a bank reconstructing an account balance from the transaction ledger.