HyperVault integration: cloud mind ⇄ sovereign chain + archive

[johnnyclem]

Summary

Implements PLAN_HYPERVAULT_INTEGRATION.md — a first-class bridge between the HyperVault cloud mind (hypervault.store) and AgentVault's ICP + Arweave stack. It makes each the missing half of the other across three tiers of the same mind:

• Hot (HyperVault / Supabase): the live, queryable, multi-device mind.
• Warm (ICP canister): the sovereign mirror — the mind DAG replayed on-chain; survives a HyperVault outage.
• Cold (Arweave): the permanent archive — a whole account is reconstructible from one transaction id + keys.

The two one-liners (also exposed as MCP tools)

# Bootstrap a HyperVault-backed agent — memories, mind history, and indices included
npx agentvault@latest hypervault bootstrap my-agent --key hv_...

# hypervault.store → fully secure, archived, blockchain-backed AgentVault
npx agentvault@latest hypervault archive --all --encrypt --network ic --arweave

What's included

New src/hypervault/ module (exported as agentvault/hypervault):

• client.ts — HyperVaultClient, typed REST over undici with retry/backoff and streamed NDJSON export/import.
• auth.ts — key resolution (--key → HYPERVAULT_API_KEY → secrets vault) and .agentvault/hypervault.json state that stores only a keyRef, never the key.
• snapshot.ts — the agentvault-hypervault-snapshot-v1 bundle: per-entry SHA-256, Merkle root, ed25519 manifest signature, AES-256-GCM encryption via the audited CanisterEncryption. Private artifacts and conversations are always encrypted.
• index/ — pure-TS weighted FTS index, cosine VectorIndex over exported embeddings, and reciprocal-rank hybrid recall with graceful FTS-only fallback.
• memory-store.ts / knowledge-store.ts / wiki-store.ts — adapters running the existing backbone/wiki interfaces against the cloud mind.
• mind-sync.ts — topological, idempotent mind-DAG replay onto a memory_repo canister, with on-chain archive receipts.
• pipeline.ts — the connect/pull/push/snapshot/archive/verify/restore/status/recall/bootstrap flows shared by the CLI and MCP server.
• mcp-server.ts — AgentVault's first native MCP server (stdio JSON-RPC, no new dependency) exposing the hypervault_* pipeline tools and the existing wiki_* tools.

CLI: new agentvault hypervault command group (connect · status · bootstrap · pull · push · snapshot · archive · verify · restore · reindex · recall), an agentvault mcp serve subcommand, and an agentvault init --hypervault flag.

Security

• Audit finding C-1 (CRITICAL) fixed: vetkeys.decryptJSON now validates the AES-256-GCM / ChaCha20-Poly1305 authentication tag before returning plaintext (previously setAuthTag was never called, so tampered ciphertext decrypted silently). EncryptedData gains an optional tag field, a matching encryptJSON helper is added, payloads with no usable tag are refused, and legacy combined-layout payloads (tag appended to ciphertext) remain supported.
• Bundle encryption uses the audited CanisterEncryption (validated GCM tags), deliberately not the legacy vetkeys path.
• hv_ keys never persist to argv/config; hypervault.json refuses to write anything that looks like a plaintext key.

Testing

New suites under tests/hypervault/** (client mock-agent contract, snapshot round-trip / tamper rejection / encryption, indices + hybrid recall, mind-sync topological order + idempotency, auth no-plaintext-key) and tests/mcp-server/** (MCP protocol conformance over stdio pipes), plus a tests/security/ regression for the C-1 fix.

Test Files  88 passed (88)
     Tests  1554 passed (1554)

npm run typecheck, npm run lint (0 errors), npm run build, and the full npm test all pass.

Docs

• docs/guides/hypervault.md — end-to-end tutorial (bootstrap → archive → resurrect).
• docs/architecture/hypervault-integration.md — three-tier architecture + normative bundle-format spec.
• README HyperVault section and CHANGELOG entry.

Notes / follow-ups

• The companion hypervault endpoints from the plan (GET /api/export, POST /api/import/vault, archive receipts) are consumed by this client and land as separate PRs in that repo. The client tolerates their absence (receipts are best-effort; export falls back gracefully).
• Webapp routes and the macOS app MCP templates (plan §5.8–5.9) are follow-on, not in this PR's critical path.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FbdRFUf2aN6kGSWhkvP5NX

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-vault	Ready	Preview, Comment	Jul 15, 2026 1:56am
agentvault	Ready	Preview, Comment	Jul 15, 2026 1:56am