---
title: "Deploy Engram"
description: "Persistent, searchable memory that AI coding agents read and write"
category: "AI/ML"
url: https://railway.com/deploy/engram-cloud
---

# Deploy Engram

Persistent, searchable memory that AI coding agents read and write

**[Deploy Engram on Railway](https://railway.com/template/engram-cloud)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/engram-cloud/manifest.json

- **Creator:** A3A
- **Category:** AI/ML
- **Total deploys:** 1

## Template content

### engram https://raw.githubusercontent.com/Gentleman-Programming/engram/v1.20.0/assets/branding/engram-logo-only.png

- **Image:** ghcr.io/gentleman-programming/engram:1.20
- **Health check:** /health
- **Public domain:** Yes

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# 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.

![Diagram of the Engram Cloud and Postgres services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789373018/engram-architecture.webp)

## 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"}`.

![Engram Cloud project atlas listing two synced code projects](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789373021/engram-projects.webp)

![Engram Cloud knowledge browser showing a saved architecture decision](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789373023/engram-memory-browser.webp)

![Engram Cloud admin overview with database and contributor counts](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789373027/engram-admin-overview.webp)

## 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

| Variable | Purpose |
|---|---|
| `ENGRAM_DATABASE_URL` | PostgreSQL connection string, wired to the Postgres service |
| `ENGRAM_CLOUD_TOKEN` | Bearer token CLI clients use for `/sync/*` |
| `ENGRAM_CLOUD_ADMIN` | Admin token for dashboard login and `/admin/*` |
| `ENGRAM_JWT_SECRET` | Signs dashboard session cookies; 32 characters minimum |
| `ENGRAM_CLOUD_ALLOWED_PROJECTS` | Server-side project allow-list; `*` accepts any name |
| `ENGRAM_CLOUD_TOKEN_PEPPER` | Enables managed per-user tokens; not the JWT secret |
| `ENGRAM_CLOUD_HOST` | Bind address; `0.0.0.0`, as the image default is loopback-only |
| `ENGRAM_PORT` | Port the runtime listens on (18080) |
| `ENGRAM_CLOUD_MAX_PUSH_BYTES` | Max chunk size on push; 8 MiB by default |

### 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

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 0.5 vCPU | 1 vCPU |
| RAM | 256 MB | 512 MB-1 GB |
| Storage | 1 GB Postgres volume | 5 GB+ per team |
| Runtime | Go binary, PostgreSQL 16+ | Same |

## 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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/engram-cloud