← Back to Docs

📖 Core Concepts

Understanding the fundamental concepts of Agent Vault Protocol

Architecture Overview

┌─────────────────────────────────────────────────────────────┐ │ AI Agent │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ LangChain │ │ CrewAI │ │ OpenClaw │ ... │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ AVP Client │ │ │ └────────┬────────┘ │ └──────────────────────────┼──────────────────────────────────┘ │ 7 Operations ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend │ │ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │ │ Memory │ │ File │ │ Keychain │ │Hardware│ │ │ │(tests) │ │(AES-256) │ │ (OS) │ │(HSM) │ │ │ └────────┘ └──────────┘ └──────────┘ └────────┘ │ └─────────────────────────────────────────────────────────────┘

🔐 Secrets

A Secret is any sensitive value that an AI agent needs to operate: API keys, passwords, tokens, certificates, etc.

Each secret has:

📁 Workspaces

A Workspace is an isolation boundary for secrets. Secrets in one workspace cannot be accessed from another.

# Production agent only sees production secrets
prod_session = client.authenticate(workspace="production")
client.retrieve(prod_session.session_id, "api_key")  # ✓ Works

# Development agent only sees dev secrets
dev_session = client.authenticate(workspace="development")
client.retrieve(dev_session.session_id, "api_key")  # Different key

Use cases:

🎫 Sessions

A Session is an authenticated context for performing operations. Sessions:

# Create a session (1 hour TTL)
session = client.authenticate(
    workspace="my-agent",
    ttl_seconds=3600
)

# Use the session for operations
client.store(session.session_id, "key", b"value")
client.retrieve(session.session_id, "key")

# Sessions expire automatically, or can be terminated
# client.terminate(session.session_id)  # Future feature

🗄️ Backends

A Backend is the storage layer for secrets. AVP supports multiple backends with different security properties:

Backend Security Description
memory None In-memory only, for testing
file AES-256 Encrypted file on disk
keychain OS-protected macOS Keychain, Windows Credential Manager, Linux SecretService
hardware FIPS 140-3 Hardware Security Module (NexusClaw)
remote Varies Network vault (HashiCorp Vault, AWS Secrets Manager)

The 7 Operations

AVP defines exactly 7 operations for interacting with the vault:

Operation Description Example
DISCOVER Query vault capabilities and backends client.discover()
AUTHENTICATE Create a session for a workspace client.authenticate("workspace")
STORE Create or update a secret client.store(sid, "key", value)
RETRIEVE Get a secret value client.retrieve(sid, "key")
DELETE Remove a secret client.delete(sid, "key")
LIST Enumerate secrets (names only) client.list_secrets(sid)
ROTATE Update with version tracking client.rotate(sid, "key", new_val)

Security Properties

🔒 Encryption at Rest

All backends (except memory) encrypt secrets before storage:

🛡️ Memory Protection

Secrets are handled carefully in memory:

🔑 Key Derivation

For password-based backends, keys are derived using PBKDF2:

Next Steps