Agent Vault Protocol

1. User invokes agent with a profile
2. Create session (UUID, agent ID, profile name, PID, timestamp)
3. Load credentials from vault + host environment
4. For each credential:
   a. Check if system variable → passthrough
   b. Evaluate profile rules (last-match-wins)
   c. Log access decision to audit trail
   d. Apply decision: allow | deny | redact
5. Inject session metadata into environment
6. Spawn agent process with filtered environment
7. On exit: mark session inactive

name: moderate               # REQUIRED. Lowercase alphanumeric + hyphens.
description: "Balanced..."   # REQUIRED. Human-readable purpose.
trustLevel: 50               # REQUIRED. 0-100 inclusive.
ttlSeconds: 3600             # REQUIRED. Max session duration. 0 = unlimited.
rules:                       # REQUIRED. Ordered array of rules.
  - pattern: "*"             #   Wildcard — match all
    access: deny             #   One of: allow, deny, redact
  - pattern: NODE_ENV        #   Exact match
    access: allow
  - pattern: AWS_*           #   Prefix match
    access: redact

function matchRule(varName, pattern):
    if pattern == "*":
        return true
    if pattern ends with "*":
        return varName starts with pattern[0..length-1]
    return varName == pattern

function checkAccess(profile, varName):
    result = "deny"                    # Default if no rules match
    for each rule in profile.rules:    # Iterate in order
        if matchRule(varName, rule.pattern):
            result = rule.access       # Overwrite with latest match
    return result

PATH  HOME  USER  SHELL  TERM  LANG  LC_ALL  TMPDIR  NODE_PATH

VAULT_REDACTED_<hex>

# Example:
AWS_SECRET_KEY=VAULT_REDACTED_a1b2c3d4
DATABASE_URL=VAULT_REDACTED_e5f6a7b8

# <hex> = cryptographically random, at least 8 hex chars (4 bytes)
# Each redaction generates a unique token

{
  "salt": "<hex-encoded random salt (32 bytes)>",
  "iv": "<hex-encoded initialization vector>",
  "tag": "<hex-encoded authentication tag>",
  "data": "<hex-encoded ciphertext>"
}

[
  {
    "key": "AWS_SECRET_KEY",
    "value": "sk-abc123...",
    "addedAt": "2026-03-03T10:30:00Z"
  }
]

function extractKeywords(content):
    lower = content.toLowerCase()
    tokens = split on whitespace + punctuation
    tokens = filter(t => t.length >= 3)
    tokens = filter(t => t not in STOPWORDS)
    tokens = deduplicate(tokens)
    return tokens[0..40]    # max 40 keywords

# CJK text: extract unigrams + bigrams instead
# No partial matching: "web" does NOT match "webhook"

score = matchRatio × confidence × freshnessMultiplier × recencyBoost

matchRatio      = matchingKeywords / queryTokens.length
confidence      = entry.confidence (0.0 to 1.0)
freshnessMultiplier = max(0, 1 - ageHours / ttlHours)  — 1.0 if no TTL
recencyBoost    = 1 + (0.1 × min(accessCount, 10) / 10) — max 1.1

Minimum score threshold: 0.1 (entries below are excluded)
Ties broken by addedAt descending (newer wins)

CREATE TABLE audit (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    sessionId TEXT NOT NULL,
    agentId TEXT NOT NULL,
    profileName TEXT NOT NULL,
    varName TEXT NOT NULL,
    action TEXT NOT NULL,
    timestamp TEXT NOT NULL
);

Created  ──▸  Active  ──▸  Revoked / Expired
   │              │                │
session ID    audit logging     PID signaled
assigned      in progress       (SIGTERM)

{
  "schema": "agentvault-portable/1.0",
  "exportedAt": "2026-03-09T10:00:00Z",
  "entries": [{ "key": "...", "value": "...", "addedAt": "..." }],
  "memories": [{ "key": "...", "content": "...", ... }]
}

{
  "schema": "agentvault-memory/1.0",
  "exportedAt": "2026-03-09T10:00:00Z",
  "memories": [{ "key": "...", "content": "...", ... }]
}

.agentvault/purchased-banks/<bank-name>/
├── descriptor.json     # Bank metadata (plaintext)
├── license.json        # Access terms (plaintext)
└── bank.encrypted      # Memory entries (encrypted)

.agentvault/
├── profiles/              # Permission profile YAML files
│   ├── restrictive.yml
│   ├── moderate.yml
│   └── permissive.yml
├── vault.json             # AES-256-GCM encrypted credentials
├── memory.json            # AES-256-GCM encrypted agent memory
├── sessions.json          # Active session tracking
├── audit.db               # SQLite audit trail
├── mcp-budget.json        # MCP rate limit budget tracking
├── purchased-banks/       # Purchased memory banks
│   └── <bank-name>/
│       ├── descriptor.json
│       ├── license.json
│       └── bank.encrypted
├── .passphrase            # Encryption passphrase (mode 0600)
└── .gitignore             # Contains: *  !.gitignore

// Success
{ "success": true, "data": { ... } }

// Failure
{ "success": false, "error": "Human-readable message", "code": "ERROR_CODE" }