Engram is designed with security as a top priority. The tool never includes sensitive data in generated Context Packs (.engram/ directory). This document outlines the security measures in place.

Engram automatically excludes the following file patterns from analysis:

• Environment files: .env, .env.*, .envrc
• Secrets and credentials: secrets.json, credentials.json, *.secret, *.key, *.pem, *.p12, *.pfx
• SSH keys: id_rsa, id_dsa, id_ecdsa, id_ed25519
• Config files with secrets: config.local.*, config.secret.*, config.private.*
• Database dumps: *.sql, *.dump
• Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml
• Build artifacts: node_modules/, dist/, build/, .next/, .cache/
• IDE files: .vscode/, .idea/, .DS_Store
• Logs: *.log, logs/

Engram scans extracted content for sensitive patterns and:

1. Excludes files containing sensitive data from analysis
2. Warns when potential sensitive data is detected
3. Redacts sensitive values when detected (in future versions)

The tool detects and excludes:

• API keys and tokens (api_key, access_token, secret_key)
• Passwords (password, passwd, pwd)
• Database connection strings (mongodb://, postgres://, etc.)
• AWS/Azure/GCP credentials
• JWT tokens
• OAuth tokens
• Stripe keys (sk_live_, pk_live_, etc.)
• GitHub tokens (ghp_, gho_, etc.)
• Email addresses (when detected in sensitive contexts)

When Engram detects potential sensitive data, it will:

1. Display warnings during build
2. Mark the validation as failed if sensitive data is detected
3. Prevent committing Context Packs with sensitive data

Example warning output:

⚠️  Security Warnings:
  ⚠️  Potential sensitive data detected at schema.databases[0]
  🚨 CRITICAL: Sensitive data detected in extracted content. Review before committing.

Always review the generated Context Pack before committing:

npx engram build
# Review Context Pack
npx engram validate

Ensure sensitive files are in your .gitignore:

.env
.env.*
*.secret
*.key
secrets/
credentials/

Before sharing Context Packs:

1. Use npx engram validate to check for issues
2. Review the generated .engram/graph/ files for sensitive data
3. Verify no connection strings are included
4. Ensure no API keys or secrets are present

If you discover a security vulnerability:

1. Do NOT create a public GitHub issue
2. Email security concerns to: [security email if you have one]
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact

✅ Automatically excludes sensitive file patterns
✅ Scans content for sensitive patterns
✅ Warns when sensitive data is detected
✅ Validates before git commits
✅ Never reads .env files or secrets

❌ Cannot detect all possible sensitive data patterns
❌ Cannot prevent manual editing of Context Pack files
❌ Cannot guarantee 100% security (always review manually)

1. Never commit Context Packs (.engram/ directory) that contain sensitive data
2. Review before committing - use npx engram validate
3. Use environment variables for secrets, never hardcode them
4. Keep Context Packs private - they may contain architectural information
5. Regular audits - periodically review Context Pack contents for sensitive data

Context Packs (.engram/ directory) are designed to be version-controlled, but:

• Review diffs carefully before committing
• Never commit if warnings indicate sensitive data
• Consider making Context Packs private/internal only
• Use npx engram validate to check before commit

If you have security concerns or questions, please open an issue or contact the maintainers.