helm-engram

helm-engram

Community-maintained Helm chart for Engram Cloud — the AI-powered persistent memory server that lets LLM agents share context and observations across sessions and team members.

---

What is this repository?

This repo ships and maintains the helm-engram/engram Helm chart — one chart, one application. It is not the upstream Engram application; for that see Gentleman-Programming/engram.

The chart packages Engram Cloud for Kubernetes with:

• Internal PostgreSQL StatefulSet (no external Helm repo needed)
• Horizontal Pod Autoscaler and PodDisruptionBudget
• Optional NetworkPolicy
• Flexible secret management (chart-managed, existingSecret, ESO, Sealed Secrets)
• Full test suite via helm-unittest (99 tests)
• Automated version tracking via UpdateCLI

---

Architecture

flowchart TD
    subgraph Cluster["Kubernetes Cluster"]
        direction TB

        ING["Ingress\n(optional)"]
        SVC["Service\nClusterIP :18080"]
        CM["ConfigMap\nHOST · PORT · PROJECTS · NO_AUTH"]
        SEC["Secret\nDATABASE_URL · JWT_SECRET\nCLOUD_ADMIN · CLOUD_TOKEN"]
        HPA["HPA (optional)"]
        PDB["PDB (optional)"]
        NP["NetworkPolicy (optional)"]

        subgraph Deployment["Deployment"]
            IC["Init Container\nwait-for-postgresql"]
            APP["engram cloud :18080\n/tmp emptyDir · UID 10001 non-root"]
            IC -->|ready| APP
            APP -.->|envFrom| CM
            APP -.->|secretKeyRef| SEC
        end

        subgraph PG["PostgreSQL StatefulSet"]
            PGC["postgres:16-alpine :5432"]
            PVC[("PVC")]
            PGC --> PVC
        end

        ING -->|HTTP/HTTPS| SVC
        SVC --> Deployment
        Deployment -->|TCP :5432| PG
        HPA -.->|scales| Deployment
        PDB -.->|protects| Deployment
        NP -.->|restricts| Deployment
    end

    AGENT(["AI Agents\nCopilot CLI · MCP clients"])
    ADMIN(["Admin\n/dashboard/admin"])

    AGENT -->|"HTTP :18080"| ING
    ADMIN -->|"adminToken"| ING

---

Quick Start

helm repo add helm-engram https://devops-ia.github.io/helm-engram
helm repo update

# Production (authenticated mode) — generate strong random secrets
helm install engram helm-engram/engram \
  --set engram.jwtSecret="$(openssl rand -hex 32)" \
  --set engram.cloudToken="$(openssl rand -hex 32)" \
  --set engram.allowedProjects="my-project" \
  --set postgresql.auth.password="$(openssl rand -hex 16)"

Dev/local only — disable auth for quick local testing:

helm install engram helm-engram/engram \
  --set engram.insecureNoAuth=true \
  --set engram.allowedProjects="my-project" \
  --set postgresql.auth.password="$(openssl rand -hex 24)"

Never use insecureNoAuth=true in production.

---

Authentication Modes

Engram Cloud enforces one of two mutually exclusive modes:

Mode	Values	Use case
Authenticated (default)	insecureNoAuth: false + cloudToken + jwtSecret	Production
Insecure	insecureNoAuth: true	Local dev / CI only

Constraints enforced by the binary (Helm will also fail-fast):

• cloudToken is required when insecureNoAuth=false
• cloudToken must be empty when insecureNoAuth=true (mutually exclusive)
• adminToken (for /dashboard/admin) and tokenPepper require insecureNoAuth=false
• tokenPepper must differ from jwtSecret
• allowedProjects is always required
• A PostgreSQL connection is always required: databaseUrl, existingSecret, or the bundled PostgreSQL with postgresql.auth.password / postgresql.auth.existingSecret

Validation lives in templates/validate.yaml, so it also runs with helm template (ArgoCD, Flux, helmfile) and not only on helm install.

When using existingSecret, the chart skips token/DSN validation — ensure your Secret contains ENGRAM_DATABASE_URL, ENGRAM_JWT_SECRET, and ENGRAM_CLOUD_TOKEN (optionally ENGRAM_CLOUD_ADMIN and ENGRAM_CLOUD_TOKEN_PEPPER).

External PostgreSQL (e.g. AWS RDS) with External Secrets Operator

postgresql:
  enabled: false

engram:
  allowedProjects: "project1,project2"
  existingSecret: engram-secrets

networkPolicy:
  enabled: true
  # ALB (target-type: ip) traffic comes from the VPC CIDR, not from a pod
  extraIngress:
    - from:
        - ipBlock:
            cidr: 10.0.0.0/16
      ports:
        - port: 18080
          protocol: TCP

extraObjects:
  - apiVersion: external-secrets.io/v1
    kind: ExternalSecret
    metadata:
      name: engram-secrets
    spec:
      secretStoreRef:
        name: aws-secretsmanager
        kind: ClusterSecretStore
      target:
        name: engram-secrets
        template:
          data:
            # Use sslmode=require for managed databases
            ENGRAM_DATABASE_URL: "postgres://{{ `{{ .username }}` }}:{{ `{{ .password | urlquery }}` }}@<rds-endpoint>:5432/engram_cloud?sslmode=require"
            ENGRAM_JWT_SECRET: "{{ `{{ .jwtSecret }}` }}"
            ENGRAM_CLOUD_TOKEN: "{{ `{{ .cloudToken }}` }}"
      data:
        - secretKey: username
          remoteRef: { key: <rds-master-secret>, property: username }
        - secretKey: password
          remoteRef: { key: <rds-master-secret>, property: password }
        - secretKey: jwtSecret
          remoteRef: { key: engram/jwt-secret }
        - secretKey: cloudToken
          remoteRef: { key: engram/cloud-token }

extraObjects are rendered with tpl, so ESO template expressions must be escaped with backticks as shown above.

---

Repository Structure

helm-engram/
├── charts/engram/          # The Helm chart
│   ├── Chart.yaml
│   ├── values.yaml         # Annotated defaults (source of truth for all config)
│   ├── values.schema.json  # JSON Schema validation
│   ├── templates/          # Kubernetes manifest templates
│   ├── tests/              # helm-unittest test suites
│   ├── ci/                 # CI values files (minimal, full, ingress)
│   └── README.md           # Chart reference — auto-generated by helm-docs
├── .github/
│   ├── workflows/          # CI: lint+test, release, version check
│   └── updatecli/          # Automated upstream version tracking
├── TESTING.md              # Local development & testing guide
└── CONTRIBUTING.md         # Contribution guidelines

---

Development

See TESTING.md for the full local development workflow. Quick reference:

# Lint
npm run lint                  # helm lint charts/engram
npm run lint:full             # lint with full CI values

# Unit tests (99 tests, 9 suites)
npm run test

# Template smoke tests
npm run template              # minimal values
npm run template:full         # all features enabled
npm run template:ingress      # ingress with TLS

# Regenerate charts/engram/README.md from README.md.gotmpl
npm run docs

Install the helm-unittest plugin once:

helm plugin install https://github.com/helm-unittest/helm-unittest --verify=false

---

Automated Version Tracking

UpdateCLI monitors Gentleman-Programming/engram releases and opens automated PRs to bump image.tag, Chart.yaml appVersion, and Chart.yaml version.

Pipeline: .github/updatecli/helm-appversion.yaml

---

Contributing

1. Fork → feature branch (feat/my-feature)
2. Change chart templates and/or values
3. Add or update tests in charts/engram/tests/
4. Run npm run test && npm run lint
5. Open a Pull Request — CI runs lint + unit tests + kind install automatically

See CONTRIBUTING.md for details.

---

Links

Engram upstream	https://github.com/Gentleman-Programming/engram
ArtifactHub	https://artifacthub.io/packages/search?repo=helm-engram
Chart reference	charts/engram/README.md
UpdateCLI	https://www.updatecli.io/

License

MIT — see LICENSE.