Veil

VEIL — Privacy Layer for Hermes Memory

When to Use

Trigger this skill before writing to MEMORY.md or USER.md when the user's message contains any of the following categories of data:

• Credentials: passwords, API keys, private keys, tokens, connection strings
• Identifiers: SSH keys, TLS certs, webhook secrets, database URLs with auth
• Personally identifiable information of third parties: full names paired with emails/phones, monetary amounts tied to named clients, addresses
• Anything the user explicitly marks as sensitive: "private", "secret", "don't tell anyone", "between us"

Common triggers in user language:

• "remember my X password is ..."
• "save my API key for ..."
• "my client Y paid Z amount"
• "don't forget the SSH key for staging is ..."

Do not trigger for: generic environment facts ("I use Ubuntu 22.04"), public project names, the user's own first name, or tool/library preferences. These belong in plain memory.

Procedure

1. Detect: Parse the user's remember-request. Identify the sensitive span(s). If unsure whether something is sensitive, ask the user once — do not default to saving in plaintext.

2. Seal: Call scripts/veil.py seal with the sensitive value and a short human-readable label (e.g., pg-prod, client-anna). The script returns an opaque reference like {{veil:pg-prod-2026a}}.

3. Write placeholder to memory: Use the memory tool to save an entry containing the placeholder instead of the plaintext.

   Good: User's Postgres prod credentials stored in VEIL: {{veil:pg-prod-2026a}}. Host: db.example.com, port 5432.

   Bad: User's Postgres prod password is hunter2.

   The non-sensitive scaffolding (host, port, which system it's for) stays in plaintext — the agent needs it to decide when to resolve.

4. Resolve at execution time: When the agent later needs the real value to run a command or make a request, call scripts/veil.py resolve <reference>. The plaintext is returned only to the tool execution context and only on the user's machine. Never write the resolved value back to MEMORY.md or echo it in a chat response.

5. Audit (if enabled): If veil.onchain_audit is true, every seal and rotate operation automatically appends SHA256(vault_state || timestamp) to the Solana audit log. No user action needed.

Commands

veil init                     one-time setup; creates vault, prompts for passphrase
veil seal <label> <value>     returns {{veil:label-hash}}
veil resolve <reference>      returns plaintext (local only)
veil list                     lists all references with labels, no values
veil rotate                   re-encrypt vault with new passphrase
veil migrate                  scan existing MEMORY.md, propose redactions
veil audit verify             check local vault matches latest on-chain digest
veil audit publish            manually publish current digest

Pitfalls

• Never log the resolved value. If the agent prints plaintext into a chat response, a log file, or a terminal command visible to another user, the leak is real. Prefer piping into stdin of the target command: veil resolve pg-prod-2026a | psql -h db.example.com ...

• Placeholders are not semantically hidden. An LLM seeing User's Postgres prod credentials: {{veil:pg-prod-2026a}} can infer the category of the secret. This is acceptable — the value is still protected — but don't claim VEIL hides the existence of credentials.

• Vault corruption is unrecoverable. If vault.age is deleted or the passphrase is forgotten, references become dangling. Back up vault.age to an external location; it is encrypted, so backup exposure is not a leak.

• On-chain audit is opt-in for a reason. It costs ~0.000005 SOL per operation and publicly reveals that the user updates their vault, even though it hides what. Users who don't want any network footprint should keep it off.

• Do not mix VEIL references across machines. Each vault is a closed world. If a user copies MEMORY.md to a new machine without the matching vault.age, references cannot be resolved.

Verification

After seal:

veil list | grep <label>            reference should appear
grep -r "<plaintext>" ~/.hermes/    should return nothing

After resolve:

veil resolve <reference>            should return exact plaintext

After on-chain audit publish:

veil audit verify                   should report "OK: local digest matches chain"

References

• references/threat-model.md — what VEIL does and does not protect against
• references/crypto-choices.md — why age, why Argon2id, why Solana for audit
• references/usage-examples.md — end-to-end examples for common workflows