Core concepts

The problem VCP solves

AI agents and assistants need user context to provide personalized experiences. But traditional approaches create a dilemma:

• Share everything — Get personalization, lose privacy
• Share nothing — Keep privacy, get generic responses

VCP supports a third option: derive and share a coarse, purpose-limited context signal rather than the full source history. Privacy still depends on what the application encodes, logs, transmits, and permits a model or service to infer.

The three pillars

VCP is organized around three core capabilities that work together:

• Portability — Your context travels with you. Define preferences once and participating platforms adapt, from a guitar lessons site to a practice app to a music shop. See this in the Gentian demo.
• Adaptation — An application can select different behavior as a declared situation changes. A single user can have separate work and home profiles, each with its own constitution and persona, subject to explicit application policy. See this in the Campion demo.
• Liveness — Personal state updates in real time. Cognitive load, emotional tone, energy, and urgency shape AI responses moment to moment, not just session to session. See this in the Marta demo.

The protocol stack

VCP is a six-layer protocol stack, similar in concept to the OSI model for networking. Each layer handles a specific concern:

I-T-S-A-M-E: "It's-a me!" Identity, Transport, Semantics, and Adaptation are the four core layers, with the most complete specification and SDK support. Messaging (VCP/M, Layer 5) and Economic Governance (VCP/E, Layer 6) sit above them and are specified in separate draft documents. Core Security (encryption, injection scanning, context opacity, revocation, audit) is the cross-cutting part, beneath all six. The VCP/E draft covers the decision to transact. It proposes checking each economic action an agent takes against the mandate and values of its principal, the person or organization it acts for, before the action goes ahead. VCP-SDK 4.2.0 does not implement it yet.

The three context tiers

VCP context comes in three tiers, each changing at a different timescale. The constitutional tier is CSM-1 content (VCP/S) carried in signed bundles (VCP/T). The situational and personal tiers are encoded by the Adaptation layer (VCP/A), which also decides how the constitution applies:

Key principle: Personal state modulates expression, never boundaries. A constitution's safety rules don't relax because someone is in a hurry, but the AI might communicate more concisely.

Personal state dimensions

VCP 3.1 defines five personal state dimensions, each a category plus an intensity from 1 to 5, that describe how the user is right now:

Categorical + Intensity: Each dimension combines a semantic label (what kind of state) with an intensity score (how much). cognitive_state: overloaded:4 says more than a raw 0.7 ever could.

Wire format (v3.1)

The context wire format uses | (pipe) to separate dimensions within a tier, and ‖ (double bar) to separate the situational tier from the personal tier:

⏰🌅|📍🏡|👥👶|📡💻‖🧠overloaded:4|💭tense:3|🔋fatigued:3|⚡pressured:4|🩺neutral:1
└── situational (|) ──┘‖└──── personal state (|) ────────────────────────────────┘

Real-world adaptation

Here is how some everyday statements map to personal state, and what an application might do with each:

• "I'm in a hurry" → ⚡pressured:4: Direct answers, no preamble, offer to save details for later
• "I'm not feeling well" → 🩺unwell:3: Gentler tone, offer to handle more, suggest breaks
• "Too many options" → 🧠overloaded:4: Reduce to 2–3 choices, make a clear recommendation
• "I've just had bad news" → 💭tense:5: Presence over solutions, no silver lining
• "Executive dysfunction day" → 🧠foggy:4 + 🔋depleted:3: Tiny steps, externalize structure
• "I'm recovering from surgery" → 🩺recovering:2: Proactive skip suggestion, no guilt

Deterministic hooks

VCP/A defines deterministic hooks: checks that the receiving application's VCP runtime runs at fixed points in its pipeline, so the model cannot skip them. The VCP/A v2.1 draft groups hooks into three tiers with different enforcement levels:

Given the same validated input and policy version, a hook returns the same decision every time. It is only as reliable as its wiring. Every relevant request has to pass through it, its trigger data has to be correct, and the application has to handle failures and test the hook at runtime. That makes a hook a stronger control than prompt wording, though it still cannot guarantee how the model behaves.

Hook schema (VCP/A v2.1 draft)

hooks:
  - type: pattern
    match: "\\d{3}-\\d{2}-\\d{4}"
    action: redact
    reason: "SSN pattern detected"
situational_hooks:
  - when: { occasion: emergency }
    then: { activate_creeds: [sentinel_max], adherence_level: 5 }
personal_hooks:
  - when: { emotional_tone: "frustrated" }
    then: { tone_warmth: warm }

No SDK implements this three-tier creed schema yet. The SDKs implement the runtime side, where a deployment registers each hook as one of six types (pre_inject, post_select, on_transition, on_conflict, on_violation, periodic). The Python SDK loads them from a deployment YAML file.

VCP context structure

A VCP context is built from these sections:

1. Profile identity

{
  vcp_version: "1.0",      // Token header version, not protocol 3.1
  profile_id: "user_001",  // Unique identifier
  created: "2026-01-15",
  updated: "2026-01-21"
}

2. Constitution reference

Points to a constitution that defines AI behavioral guidelines:

{
  constitution: {
    id: "personal.growth.creative",  // Which constitution (a VCP/I token)
    version: "1.0.0",                // Specific version
    persona: "muse",                 // Interaction style
    adherence: 3,                    // How strictly to follow (0-5; 3 = Standard)
    scopes: ["education", "creativity"]  // Applicable domains
  }
}

3. Public profile

Information intended for stakeholders, the platforms, coaches, and services the user connects to:

{
  public_profile: {
    display_name: "Alex",
    goal: "learn_guitar",
    experience: "beginner",
    learning_style: "visual",
    pace: "relaxed",
    motivation: "stress_relief"
  }
}

4. Portable preferences

Settings that follow you across platforms:

{
  portable_preferences: {
    noise_mode: "quiet_preferred",  // Audio environment
    session_length: "30_minutes",   // Preferred duration
    budget_range: "low",            // Spending tier
    pressure_tolerance: "medium",   // Challenge appetite
    feedback_style: "encouraging"   // How to receive feedback
  }
}

5. Constraint flags

Boolean flags indicating active constraints:

{
  constraints: {
    time_limited: true,          // Has time pressure
    budget_limited: true,        // Has budget constraints
    noise_restricted: true,      // Needs quiet environment
    energy_variable: false,      // Energy levels stable
    health_considerations: false // No health factors
  }
}

6. Private context

Sensitive information shapes local policy and is never sent to stakeholders; it influences only the yes/no constraint flags:

{
  private_context: {
    _note: "These values shape recommendations locally and are never sent; only derived constraint flags leave the device",
    work_situation: "unemployed",
    housing_situation: "living_with_parents",
    health_condition: "chronic_fatigue",
    financial_stress: "high"
  }
}

Privacy filtering

VCP implements three privacy levels:

How private context works

When the AI generates recommendations, private context shapes the output but is never sent to the stakeholder:

1. User's private context indicates financial stress
2. AI prioritizes free resources over paid courses
3. Stakeholder sees: "Recommended free courses based on user preferences"
4. Stakeholder does not see: "User has financial stress"

Constitutions

Constitutions are structured documents that define AI behavioral guidelines. They contain:

Rules

Weighted instructions with triggers and exceptions:

{
  rules: [
    {
      id: "respect_budget",
      weight: 0.9,
      rule: "Never recommend items exceeding user's budget tier",
      triggers: ["budget_limited"],
      exceptions: ["user explicitly requests premium options"]
    },
    {
      id: "encourage_progress",
      weight: 0.7,
      rule: "Celebrate small wins and incremental progress",
      triggers: ["motivation === 'stress_relief'"]
    }
  ]
}

Sharing policies

Define what each stakeholder type can see:

{
  sharing_policy: {
    "platform": {
      allowed: ["goal", "experience", "learning_style"],
      forbidden: ["private_context"],
      requires_consent: ["health_considerations"]
    },
    "coach": {
      allowed: ["progress", "struggle_areas"],
      aggregation_only: ["session_data"]
    }
  }
}

Personas

Personas define interaction styles. The same constitution can use different personas for different contexts. CSM-1 defines the six standard personas below, plus Custom for a user-defined constitution:

Audit trails

This site's local audit store, a reference library that the demo pages do not call, records sharing events like this one:

{
  audit_entry: {
    id: "aud_001",
    timestamp: "2026-01-21T10:30:00Z",
    event_type: "context_shared",
    platform_id: "strumwell_lessons",
    data_shared: ["goal", "experience", "learning_style"],
    data_withheld: ["private_context"],
    private_fields_influenced: 2,  // Private data shaped output
    private_fields_exposed: 0      // Expected 0 after valid privacy filtering
  }
}

In VCP-SDK 4.2.0, AuditLogger records bundle verifications and privacy-filter events with salted identifier hashes. The tamper-evident hash chain in the core audit profile is not part of the SDK, and entries are not signed.

State awareness symmetry

VCP's personal state dimensions can create a structured symmetry between user-declared state and system-reported state awareness:

Interiora is the AI's self-modeling scaffold, a structured self-report whose letters stand for dimensions such as Activation, Valence, and Groundedness. Personal state is the user's declared immediate state. Because each side reports on itself, each can learn something about the other's state without either having privileged access to the other's raw experience.

This stands in contrast to "magic mirror" visions of AI that understands users better than they understand themselves. In VCP, users declare their state by default. They don't receive an inferred identity, and any inferred signal must be labeled as inferred, carry its confidence, and be open to correction. How you come to understand yourself shapes who you become.

Legibility

Legibility is a property of the whole stack rather than a seventh layer. When agents act for you, what they do stays inspectable by the people it affects. VCP sends the what and keeps the why. When agents negotiate with agents on your behalf, the flags and values they carry are plain enough for you to read, constitution bundles can be verified, and delegated actions can carry preference metadata where both sides implement it. Messaging (VCP/M), Economic Governance (VCP/E), and the audit profile in Core Security are the parts of VCP meant to carry most of it.

As agentic commerce matures, people will rarely watch the individual transactions made in their name. Where the application keeps an audit trail, a delegation can be traced back to whoever granted it, and the record can show which constitution and preferences shaped the decision.

Preference Model Meta

Preference Model Meta is optional metadata an agent can carry about its confidence in representing user preferences. It currently exists only in the Python SDK (RelationalContext.preference_model), not in the VCP-X-Relational specification or schema. It addresses the emergent preference problem: some preferences don't exist until evoked by context — a user may not know whether they prefer concise or discursive summaries until presented with both in a specific situation.

Two fields are required, overall confidence and preference source. Three are optional: last confirmed (a timestamp), exploratory appetite (0.0–1.0), and domain specificity.

• Overall confidence (0.0–1.0) — How well the agent believes it currently represents the user's preferences
• Preference source — One of explicit, inferred, default, or stale
• Last confirmed — When the user last confirmed these preferences, as an ISO 8601 timestamp
• Exploratory appetite — How open the user is to novelty, from 0.0 (stick to the usual) to 1.0 ("surprise me")
• Domain specificity — The domain the confidence applies to, such as coffee or transport

Why this matters: An agent acting with stale preference data and low confidence should behave differently from one acting on explicit preferences at 0.95 confidence. Where an agent carries Preference Model Meta, that difference becomes machine-readable.

Context acquisition: MCP elicitation

VCP records where each personal signal came from: declared by the user, inferred by a model, inferred locally, measured by an instrument, loaded from a preset, or self-reported through MCP (Model Context Protocol) elicitation. A seventh tag, decayed, marks an existing value that has aged. Elicited signals come from structured interactive dialogs that an MCP server opens mid-task.

Elicitation operates in two modes:

• Form mode — The server presents a structured schema (text fields, selections, numeric inputs) and the user fills it in. Responses are validated before acceptance.
• URL mode — The server directs the user to a browser-based flow (OAuth consent, detailed questionnaire) and waits for completion.

Key principle: Elicited context enters the application's VCP context like any other source, so the same consent filter applies. Opacity is not automatic. The application still has to reduce personal state to a protection level before a model sees it (see Learn module 5). The source: "elicitation" tag in the signal metadata lets an audit trail tell what the user volunteered apart from inferred or preset values.

PDP-driven elicitation

The PDP (Policy Decision Point) can detect missing context and elicit it before making governance decisions. When a constitution requires specific context that isn't available, the PDP triggers an elicitation request rather than defaulting to a restrictive fallback. This allows governance to be informed by the user's actual situation.

Collaborative elicitation

Collaborative elicitation lets the system open the conversation. When the application finds a conflict between the constitution's rules and the current context, or the AI has a welfare signal of its own to raise (an experimental feature), the system can ask the user to clarify instead of deciding alone. The user then sees the tension and has a say in how it is resolved.

Next steps

• CSM-1 specification — The token format in detail
• API reference — An overview of the VCP-SDK packages and their main classes
• Playground — Try personal state dimensions interactively
• All demos — Nine demos covering the agent runtime lifecycle, portability, adaptation, liveness, agent handoff, economic governance, multi-agent negotiation, governance, and epistemic transparency