At-Rest Encryption

YantrikDB Server can encrypt all memory data at rest using AES-256-GCM. This includes the memory text, embeddings, metadata, and graph edges — everything sensitive in the SQLite database file.

Why this matters

Cognitive memory is intimate data. A YantrikDB instance stores:

• Personal facts and preferences
• Relationships and emotional context
• Decisions and reasoning traces
• Conversation history

If someone gets the disk image (theft, backup leak, snapshot exfiltration), they shouldn’t be able to read any of it. At-rest encryption is the bottom layer of trust.

Enabling encryption

Encryption is opt-in. Add an [encryption] section to your config:

Option A: Auto-generated key

[encryption]
auto_generate = true

On first startup, the server creates master.key (32 random bytes) in the data directory with 0600 permissions. Keep this file safe — losing it = losing all data.

Option B: Explicit key file

[encryption]
key_path = "/etc/yantrikdb/master.key"
auto_generate = false

Generate the key first:

yantrikdb encryption gen-key --output /etc/yantrikdb/master.key

Option C: Hex string (env-friendly)

[encryption]
key_hex = "your-64-char-hex-string"

Or set via environment variable for secrets management:

export YANTRIKDB_ENCRYPTION_KEY_HEX=$(cat /run/secrets/yantrikdb-key)
yantrikdb serve --config yantrikdb.toml

Verification

When encryption is enabled, you’ll see this on startup:

INFO yantrikdb: encryption: enabled (AES-256-GCM)

Versus disabled:

WARN yantrikdb: encryption: disabled — set [encryption] to enable at-rest encryption

You can verify the on-disk file is unreadable:

strings /var/lib/yantrikdb/default/yantrik.db | grep "your sensitive text"
# (no output — text is encrypted)

Cluster encryption

In a cluster, all nodes must use the same master key. The replicated oplog payloads are plaintext on the wire (under TLS), but each node encrypts independently to its own SQLite file. Sharing the key ensures any node can serve queries after failover.

Recommended setup:

1. Generate the key once on node1: yantrikdb encryption gen-key
2. Securely copy to node2 and node3 (e.g. via SSH, KMS, or secrets manager)
3. Configure each node to read it via key_path

What is and isn’t encrypted

Component	Encryption
Memory text	✅ AES-256-GCM
Embeddings	✅ AES-256-GCM
Metadata JSON	✅ AES-256-GCM
Graph edges	✅ AES-256-GCM
Oplog entries	✅ AES-256-GCM
control.db (databases + tokens)	❌ Plaintext (no sensitive data)
Wire protocol	TLS only (Phase 2)
HTTP gateway	TLS only

Caveats

• Encryption + replication backfill: in v0.5.x, follower nodes that receive replicated memories cannot backfill embeddings on encrypted databases (the engine method needed to write encrypted embeddings is not yet exposed in the public core crate). For encrypted clusters today, recall on followers will return empty until the data is re-encrypted manually. Fix tracked for the next release.
• Key rotation is not yet supported. Plan ahead and back up your key immediately.
• Backup files are also encrypted when you yantrikdb export a database with encryption enabled.

Operational best practices

1. Back up the key separately from the data. A backup with both is no better than no encryption.
2. Use a hardware-backed key store if you have one (HSM, KMS, vault).
3. Set restrictive file permissions on the key file (chmod 600).
4. Monitor for key file changes with auditd or similar.
5. Document the key escrow process so you can recover from staff turnover.