Agent Residency Quickstart

Agent residency lets a long-running agent maintain continuity across sessions: reading prior context, writing journal events, and detecting stale state. This requires FEATURE_AGENT_RESIDENCY=true on the VaultCrux instance.

Required environment variables

VAULTCRUX_API_URL
VAULTCRUX_API_KEY
VAULTCRUX_TENANT_ID

Feature flag requirement

Agent residency is disabled by default. Confirm it is active before using these tools:

curl -sS "$VAULTCRUX_API_URL/capabilities" \
  -H "x-tenant-id: $VAULTCRUX_TENANT_ID" \
  -H "x-api-key: $VAULTCRUX_API_KEY" | grep agent_residency

If the capability is absent, contact your VaultCrux operator to enable FEATURE_AGENT_RESIDENCY=true.

Continuity model

Each agent session is associated with an agent_id. On session start the agent reads its prior context (decisions, pins, journal entries). On session end it writes a journal event. Stale pins are entries that reference evidence the agent acted on that has since changed in the corpus.

1) Read session context

curl -sS "$VAULTCRUX_API_URL/rpc" \
  -H "content-type: application/json" \
  -H "x-tenant-id: $VAULTCRUX_TENANT_ID" \
  -H "x-api-key: $VAULTCRUX_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "ctx-1",
    "method": "get_session_context",
    "params": {"agent_id": "agent-1"}
  }'

Returns prior journal entries, active pins, and any open decisions for this agent.

2) Write a journal event

curl -sS "$VAULTCRUX_API_URL/rpc" \
  -H "content-type: application/json" \
  -H "x-tenant-id: $VAULTCRUX_TENANT_ID" \
  -H "x-api-key: $VAULTCRUX_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "jrnl-1",
    "method": "write_journal_event",
    "params": {
      "agent_id": "agent-1",
      "event_type": "decision",
      "payload": {"summary": "Approved quarterly report draft", "doc_id": "report-2026-q1"}
    }
  }'

3) Read journal history

curl -sS "$VAULTCRUX_API_URL/rpc" \
  -H "content-type: application/json" \
  -H "x-tenant-id: $VAULTCRUX_TENANT_ID" \
  -H "x-api-key: $VAULTCRUX_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "jrnl-2",
    "method": "read_journal",
    "params": {"agent_id": "agent-1", "limit": 20}
  }'

4) Check for stale pins

curl -sS "$VAULTCRUX_API_URL/rpc" \
  -H "content-type: application/json" \
  -H "x-tenant-id: $VAULTCRUX_TENANT_ID" \
  -H "x-api-key: $VAULTCRUX_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "pins-1",
    "method": "check_stale_pins",
    "params": {"agent_id": "agent-1"}
  }'

Returns any pins referencing evidence that has been updated or removed since the pin was created. Agents should re-evaluate decisions that depend on stale pins before acting.