Deploy Engram

Deploy and Host Engram on Railway

Engram is an open-source persistent memory system for AI coding agents. Your agent forgets everything when a session ends, so every new conversation re-explains the same decisions and the same bug you already fixed. Engram gives it searchable, structured memory instead: a single Go binary with SQLite and FTS5 that any MCP-compatible agent — Claude Code, Gemini CLI, OpenCode, Cursor, Windsurf, VS Code Copilot — reads and writes through a fixed set of tools. Engram Cloud is the server half, and the part you self-host: a project-scoped replication endpoint that keeps a developer's memory in step across machines and gives a team one shared index.

Deploy Engram Cloud on Railway and the runtime arrives pre-configured. The template provisions two services: engram, the engram cloud serve runtime from the official ghcr.io/gentleman-programming/engram image, and Postgres, Railway's managed PostgreSQL, holding every replicated chunk, session, observation and audit event. Only engram gets a public domain; Postgres stays private. Each machine's local SQLite database stays authoritative — nothing is uploaded until someone runs an explicit engram sync --cloud --project — so self-host Engram on Railway when you want shared memory and browser visibility without handing your engineering context to a third party.

Getting Started with Engram on Railway

There are no default credentials to change. The template generates ENGRAM_CLOUD_TOKEN (the sync bearer token) and ENGRAM_CLOUD_ADMIN (the dashboard admin token) at deploy time; read them from the engram service's Variables tab. Open /dashboard and you are redirected to a login page — paste ENGRAM_CLOUD_ADMIN into the token field. The dashboard stays empty until a client pushes, which is the real first step.

Install the CLI on your own machine (brew install gentleman-programming/tap/engram, or a release binary), point it at the deployment, enroll a project, then sync it:

engram cloud config --server https://your-app.up.railway.app
export ENGRAM_CLOUD_TOKEN=
engram cloud enroll my-project
engram sync --cloud --project my-project

A successful push prints the new chunk id with its session and observation counts, and the Projects tab shows the project immediately. To confirm replication works, run engram sync --cloud --import --project my-project on a second machine with an empty store — the memories from the first appear there. The health endpoint is GET /health, returning {"status":"ok","service":"engram-cloud"}.

About Hosting Engram

Engram stores structured observations — bug fixes, decisions, discoveries, conventions, constraints — rather than raw transcripts, and keys evolving topics so an agent updates a decision instead of stacking contradictory copies of it. Engram Cloud adds replication and human visibility without changing where the truth lives.

• Local-first — the endpoint holds compressed, project-scoped chunks; local SQLite is authoritative.
• Explicit sync — every push and pull names one project. There is no implicit "sync all" mode.
• Browser dashboard — projects, sessions, observations, prompts, contributors, stats, audit log.
• Bearer-token API — /sync/push, /sync/pull and /admin/* reject unauthenticated requests; per-person tokens are granted project by project.
• Deterministic failure reasons — blocked_unenrolled, policy_forbidden, auth_required, not silent drift.

The engram service is a stateless Go HTTP server, so it needs no volume and can be redeployed freely; all durable state sits in Postgres, on a Railway volume with managed backups.

Why Deploy Engram on Railway

Railway removes the parts of self-hosting Engram Cloud that are not about memory:

• HTTPS and a public domain are issued automatically, which bearer-token clients require.
• Managed PostgreSQL is wired to the runtime by reference, not a copied connection string.
• The private network keeps the database off the public internet.
• Secrets are generated at deploy time, not pasted from a .env file.
• Upgrading the image is one click.

Common Use Cases

• One developer, several machines — a laptop and a desktop working from the same project memory instead of re-teaching each agent.
• Team conventions that survive turnover — a shared index of why the codebase is shaped as it is.
• Onboarding context — point a new engineer's agent at an enrolled project so its first session knows the decisions.

Dependencies for Engram

• engram — ghcr.io/gentleman-programming/engram:1.20. Its default command is cloud serve, so this is the sync API and the dashboard in one process. Source: github.com/Gentleman-Programming/engram (MIT).
• Postgres — Railway's managed postgres-ssl:18, holding chunks, sessions, observations, prompts, principals and audit events; the schema is created on first boot.

Environment Variables Reference

Deployment Dependencies

• Source and docs: github.com/Gentleman-Programming/engram, engram.gentlemanprogramming.com
• Container image: ghcr.io/gentleman-programming/engram
• Runtime: Go 1.25 on Alpine; PostgreSQL 16 or newer

Hardware Requirements for Self-Hosting Engram

Self-Hosting Engram with Docker

Engram Cloud publishes linux/amd64 and linux/arm64 images, and upstream advises running the published image rather than building from source. A minimal Compose file:

services:
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: engram, POSTGRES_PASSWORD: change-me, POSTGRES_DB: engram_cloud }
  cloud:
    image: ghcr.io/gentleman-programming/engram:1.20
    depends_on: [postgres]
    environment:
      ENGRAM_DATABASE_URL: postgres://engram:change-me@postgres:5432/engram_cloud?sslmode=disable
      ENGRAM_CLOUD_TOKEN: a-long-random-token
      ENGRAM_JWT_SECRET: a-different-32-character-secret
      ENGRAM_CLOUD_ALLOWED_PROJECTS: "*"
      ENGRAM_CLOUD_HOST: 0.0.0.0
      ENGRAM_PORT: "18080"
    ports: ["18080:18080"]

Terminate TLS in front of it — authenticated clients refuse a bearer token over plain HTTP. Railway does that for you.

Is Engram Free to Self-Host?

Engram is MIT-licensed and free — no paid tier, seat count or feature gate; the binary, the MCP server, the dashboard and the cloud runtime all live in one repository. Self-hosting on Railway costs only the infrastructure the two services use: for a small team, a fraction of a vCPU and a modest Postgres volume.

FAQ

What is Engram? An open-source persistent memory system for AI coding agents. It stores structured observations in SQLite with full-text search and exposes them over MCP, an HTTP API, a CLI and a terminal UI, so any MCP-compatible agent recalls earlier work rather than starting from zero.

What does this Railway template deploy? Two services: the engram cloud serve runtime from the official image with a public HTTPS domain, and Railway's managed PostgreSQL on the private network. Every required secret is generated at deploy time.

Why does the template include a PostgreSQL database? The cloud runtime keeps no local state — replicated chunks, sessions, observations, principals and the audit log all live in PostgreSQL. That lets the runtime be redeployed without losing anything, and is why the engram service needs no volume.

How do I connect my AI coding agent to self-hosted Engram? Agents talk to the local engram binary over MCP stdio, not to the server directly. Run engram setup for your tool, then point that machine at the deployment with engram cloud config --server and enroll the projects you want replicated.

Can several developers share one self-hosted Engram Cloud endpoint? Yes. With ENGRAM_CLOUD_TOKEN_PEPPER set, engram cloud bootstrap admin --username --grant-project --issue-token mints per-person tokens, and managed principals are deny-by-default. Narrow ENGRAM_CLOUD_ALLOWED_PROJECTS from * to a comma-separated list of real project names before inviting other people — it is enforced server-side on every sync call.