selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

GitHubWebsite
Engram logo

Self-host Engram

v3.6.0

Persistent memory layer for AI coding agents via MCP

ReleaseOpen SourceMIT
GitHubWebsite
Install
Updated10 hours ago
LanguageGo
Setup difficultyEasy
Stars
7 665
Ports
7437 (Local HTTP API served by `engram serve` (JSON on 127.0.0.1)), 8080 (Engram Cloud server runtime (`engram cloud serve`) default port when run from source)
Docker
ghcr.io/gentleman-programming/engram
Install with Docker Compose
Engram terminal UI dashboardTUI recent observations listTUI observation detail viewTUI search results

What is Engram?

Engram gives AI coding agents a persistent, searchable memory so they stop losing context between sessions. It stores curated observations, prompts and session summaries in a single SQLite database with FTS5 full-text search, located at ~/.engram/engram.db. Everything ships as one Go binary with no runtime dependencies: it exposes a CLI, a local HTTP API (port 7437 by default), a stdio MCP server with dozens of memory tools, and a vim-style terminal UI. It is agent-agnostic — engram setup writes configuration for fourteen coding agents such as Claude Code, Codex, Gemini CLI, Cursor and Windsurf, and any MCP-compatible client can connect. Memories are project-scoped, related or conflicting entries are flagged for the agent, and Git Sync exports compressed chunks so history can move across machines; Engram also offers optional conflict scanning, read-only engram doctor diagnostics, and a beta tool that turns stored memories into an Obsidian graph. Install it with Homebrew, go install, or a release archive for macOS, Linux and Windows, and optionally deploy the self-hosted Engram Cloud replication server with a browser dashboard using Docker Compose and Postgres. The project is MIT-licensed (names and logos are trademarked) and maintained by Alan Buscaglia's Gentleman Programming organisation.

Should you self-host Engram?

Engram scores 66/100 on selfhost.directory (how scoring works) and ranks #37 of 209 in AI Agents. It has 7 665 GitHub stars.

It shipped 6 stable releases in the past year. The latest, v3.6.0, came out on 24 October 2026. New versions land roughly every 1 days.

Setup is easy: most people get it running in one sitting. An official Docker image is available. It is MIT-licensed and written mostly in Go.

Its closest alternative on selfhost.directory is Orca (91/100, 108 739 stars). It scores higher overall, so compare the two before you pick. See Engram vs Orca side by side.

Features

  • Agent setup automation
  • Background autosync
  • Cloud replication with dashboard
  • Conflict Detection
  • Full-Text Search
  • Git Sync
  • MCP Server
  • Obsidian knowledge graph exportMarked beta by the project.
  • Operational diagnostics
  • Persistent agent memory
  • Project-scoped memory
  • REST API
  • Session handoff summaries
  • Terminal UI

Engram README

How to install Engram

Install Engram with Docker Compose

Environment variables
ENGRAM_DATABASE_URL, ENGRAM_CLOUD_HOST, ENGRAM_PORT, ENGRAM_CLOUD_TOKEN, ENGRAM_JWT_SECRET, ENGRAM_CLOUD_ALLOWED_PROJECTS
# Start cloud + Postgres
$ docker compose -f docker-compose.cloud.yml up -d
# Configure & enroll
$ engram cloud config --server http://127.0.0.1:18080
$ engram cloud enroll my-project
# Sync & verify
$ engram sync --cloud --project my-project

Self-hosts the optional Engram Cloud server (GHCR image linux/amd64 and linux/arm64); the local memory core itself needs no Docker.

How to configure Engram

  • ENGRAM_AGENT_CLI(unset)LLM runner name used by `engram conflicts scan --semantic` and the HTTP `/conflicts/scan` endpoint. Accepted values: `claude`, `opencode`.

    LLM runner name used by `engram conflicts scan --semantic` and the HTTP `/conflicts/scan` endpoint. Accepted values: `claude`, `opencode`.

  • ENGRAM_CLOUD_ADMIN(unset)Optional legacy dashboard-admin token in authenticated cloud serve mode. It can access dashboard admin read surfaces, project sync controls, and audit logs, but not managed-user, token, or grant mutations. Ignored/rejected in insecure mode.

    Optional legacy dashboard-admin token in authenticated cloud serve mode. It can access dashboard admin read surfaces, project sync controls, and audit logs, but not managed-user, token, or grant mutations. Ignored/rejected in insecure mode.

  • ENGRAM_CLOUD_ALLOWED_PROJECTS(unset)Comma-separated project allowlist enforced by `engram cloud serve`. Required in both token-auth and insecure modes. Use `*` to allow all projects (dev/internal deploys) — bypasses per-project name enforcement while still requiring a non-empty project on each request.

    Comma-separated project allowlist enforced by `engram cloud serve`. Required in both token-auth and insecure modes. Use `*` to allow all projects (dev/internal deploys) — bypasses per-project name enforcement while still requiring a non-empty project on each request.

  • ENGRAM_CLOUD_AUTOSYNC(unset — disabled)Set to `1` to enable background autosync. Requires `ENGRAM_CLOUD_TOKEN` and `ENGRAM_CLOUD_SERVER` to also be set.

    Set to `1` to enable background autosync. Requires `ENGRAM_CLOUD_TOKEN` and `ENGRAM_CLOUD_SERVER` to also be set.

  • ENGRAM_CLOUD_HOST127.0.0.1Bind host for `engram cloud serve`.

    Bind host for `engram cloud serve`.

  • ENGRAM_CLOUD_INSECURE_NO_AUTH(unset)Set to `1` for local insecure cloud serve (no auth). Cannot be combined with `ENGRAM_CLOUD_TOKEN`.

    Set to `1` for local insecure cloud serve (no auth). Cannot be combined with `ENGRAM_CLOUD_TOKEN`.

  • ENGRAM_CLOUD_MAX_PUSH_BYTES8388608Max cloud push payload bytes.

    Max cloud push payload bytes.

  • ENGRAM_CLOUD_SERVER(unset)Cloud server URL used by the autosync manager and `engram sync --cloud`.

    Cloud server URL used by the autosync manager and `engram sync --cloud`.

  • ENGRAM_CLOUD_TOKEN(unset)Bearer token required in authenticated `engram cloud serve` mode.

    Bearer token required in authenticated `engram cloud serve` mode.

  • ENGRAM_CLOUD_TOKEN_PEPPER(unset)Dedicated secret used to hash managed cloud tokens. Required both to issue tokens via `engram cloud bootstrap admin --issue-token` (and the admin API/dashboard) and to enable managed-token authentication on `engram cloud serve`. Distinct from `ENGRAM_JWT_SECRET` on purpose — see Managed users, tokens, and CLI bootstrap.

    Dedicated secret used to hash managed cloud tokens. Required both to issue tokens via `engram cloud bootstrap admin --issue-token` (and the admin API/dashboard) and to enable managed-token authentication on `engram cloud serve`. Distinct from `ENGRAM_JWT_SECRET` on purpose — see Managed users, tokens, and CLI bootstrap.

  • ENGRAM_DATABASE_URL(unset)Postgres DSN for `engram cloud serve`.

    Postgres DSN for `engram cloud serve`.

  • ENGRAM_DATA_DIR~/.engramEngram CLI data directory. Empty or whitespace-only values use the platform default; nonblank values are used as provided.

    Engram CLI data directory. Empty or whitespace-only values use the platform default; nonblank values are used as provided.

  • ENGRAM_HTTP_TOKEN(unset — HTTP rescue route not served; CLI repair still available)Optional Bearer auth for the local HTTP server. When set, `DELETE /sessions/{id}`, `DELETE /observations/{id}`, `DELETE /prompts/{id}`, `GET /export`, and `POST /import` require `Authorization: Bearer <token>`. `POST /projects/rescue-ownership` (and deprecated alias `POST /projects/migrate`) always requires a configured token and matching Bearer credential. Comparison is constant-time. Token is re

    Optional Bearer auth for the local HTTP server. When set, `DELETE /sessions/{id}`, `DELETE /observations/{id}`, `DELETE /prompts/{id}`, `GET /export`, and `POST /import` require `Authorization: Bearer <token>`. `POST /projects/rescue-ownership` (and deprecated alias `POST /projects/migrate`) always requires a configured token and matching Bearer credential. Comparison is constant-time. Token is re

  • ENGRAM_HTTP_WRITE_TIMING(unset — disabled)Set to exactly `1` in the local HTTP server environment to log one privacy-safe timing record for each session registration, observation save, or passive capture. See HTTP write timing diagnostics.

    Set to exactly `1` in the local HTTP server environment to log one privacy-safe timing record for each session registration, observation save, or passive capture. See HTTP write timing diagnostics.

  • ENGRAM_JWT_SECRET(unset)Required in authenticated cloud serve mode. Must be explicitly set to a non-default value.

    Required in authenticated cloud serve mode. Must be explicitly set to a non-default value.

  • ENGRAM_MEM_SAVE_TIMING(unset — disabled)Set to exactly `1` in the MCP server environment to log one privacy-safe stage timing record per `mem_save` invocation to stderr. See mem_save timing diagnostics.

    Set to exactly `1` in the MCP server environment to log one privacy-safe stage timing record per `mem_save` invocation to stderr. See mem_save timing diagnostics.

  • ENGRAM_NO_UPDATE_CHECK(unset — eligible commands check for updates)Set to `1` to disable GitHub release update checks for every caller, including the TUI. `true`, `yes`, and `on` are also accepted.

    Set to `1` to disable GitHub release update checks for every caller, including the TUI. `true`, `yes`, and `on` are also accepted.

  • ENGRAM_PORT7437Override HTTP server port. Use an unsigned decimal value from `1` through `65535`; invalid values fall back to `7437` in `engram serve` and Claude Bash hooks.

    Override HTTP server port. Use an unsigned decimal value from `1` through `65535`; invalid values fall back to `7437` in `engram serve` and Claude Bash hooks.

  • ENGRAM_PROJECTcwd-detected projectProcess-level default project override for `current` project-scoped operations. Precedence: explicit request project (`engram save --project`, an MCP tool `project` argument) → process override (`engram mcp --project`, then `ENGRAM_PROJECT`) → cwd detection. The value must be a project name, not a path. Explicit/process values are checked against known context when an operation MUST NOT establish

    Process-level default project override for `current` project-scoped operations. Precedence: explicit request project (`engram save --project`, an MCP tool `project` argument) → process override (`engram mcp --project`, then `ENGRAM_PROJECT`) → cwd detection. The value must be a project name, not a path. Explicit/process values are checked against known context when an operation MUST NOT establish

  • ENGRAM_SOCKET(unset)POSIX-only Unix-domain socket path for `engram serve` and Claude Bash hooks. Socket mode listens exclusively on this path; it cannot be combined with an explicit `ENGRAM_PORT` or positional port. The default TCP listener remains unchanged when unset. PowerShell stays TCP-only. Bash hooks warn on stderr if socket transport cannot preserve memory capture.

    POSIX-only Unix-domain socket path for `engram serve` and Claude Bash hooks. Socket mode listens exclusively on this path; it cannot be combined with an explicit `ENGRAM_PORT` or positional port. The default TCP listener remains unchanged when unset. PowerShell stays TCP-only. Bash hooks warn on stderr if socket transport cannot preserve memory capture.

  • ENGRAM_TIMEZONEsystem localTimezone for timestamp display in the TUI and cloud dashboard. Accepts any IANA zone name (e.g. `America/New_York`, `Europe/Berlin`). Falls back to system local time when unset or invalid.

    Timezone for timestamp display in the TUI and cloud dashboard. Accepts any IANA zone name (e.g. `America/New_York`, `Europe/Berlin`). Falls back to system local time when unset or invalid.

Engram releases & version history

Even more releases RSS

FAQ

What should I save first?

Save a real decision or bug fix rather than a meaningless sample note, so you can judge retrieval quality.

What makes search good?

Structured content is the signal: precise titles and summaries written by the agent keep FTS5 retrieval useful.

Does it store raw tool calls?

By default no; Engram keeps curated memory — observations, prompts, summaries and context retrieval.

Does it work only with Claude Code?

No, Engram is agent-agnostic and works with any MCP-compatible client.

Does Engram require a separate server process?

Not always: MCP can run directly over stdio, though some plugin flows also use the HTTP server for session orchestration.

More in Knowledge Management

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…