Skip to content

feat(security): optional encryption at rest for engram.db #182

@GravityZenAI

Description

@GravityZenAI

Feature Description

~/.engram/engram.db is a plaintext SQLite database. Anyone with filesystem access can read all stored decisions, architectural secrets, API patterns, bug details, and potentially sensitive context. This is a concern for:

  • Shared machines (offices, labs, pair programming stations)
  • Git sync — pushing engram.db to a repo exposes everything in commit history
  • Laptop theft/loss — full disk encryption isn't always enabled
  • Compliance — some organizations require encryption at rest for developer tools

Proposal

Optional encryption at rest using SQLCipher (drop-in SQLite replacement) or application-level AES-256 encryption.

Configuration:

# engram.toml
[security]
encrypt = true
key_source = "keyring"  # options: "keyring", "env:ENGRAM_KEY", "prompt"

Implementation options (in order of preference):

  1. SQLCipher — transparent, encrypts the entire database file. Go bindings exist (github.com/mutecomm/go-sqlcipher). Most robust.
  2. Application-level encryption — encrypt content and title fields before writing, decrypt on read. Simpler to implement, but FTS5 can't index encrypted content (would need a separate plaintext FTS index that's rebuilt on startup).
  3. Hybrid — encrypt the entire DB with SQLCipher for storage, but this is the recommended approach.

Key management:

  • Keyring (default): OS credential store (Windows Credential Manager, macOS Keychain, Linux Secret Service)
  • Environment variable: ENGRAM_KEY=... for CI/automated environments
  • Interactive prompt: Asked once per session, kept in memory

Migration path:

  • engram encrypt — encrypts an existing plaintext database (creates backup first)
  • engram decrypt — decrypts back to plaintext (for migration/debugging)
  • New installations with encrypt = true start encrypted from day one

Design principles

  • Opt-in: Zero cost when disabled. Default remains plaintext for simplicity
  • Transparent: Once configured, all MCP tools, CLI, and TUI work identically
  • Recoverable: Backup before encryption, decrypt command available
  • Git sync compatible: Encrypted DB syncs normally (opaque blob)

Affected Area

Store (SQLite driver), CLI (new commands), Configuration

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions