Installation

Install Engram on macOS, Linux, or Windows

Engram is distributed as a single binary with zero runtime dependencies. Choose the installation method that works best for your platform.

Homebrew (macOS / Linux)

The easiest way to install on macOS or Linux:

brew install gentleman-programming/tap/engram

Verify installation:

engram version

Upgrade to Latest

brew update && brew upgrade engram

Migrating from Cask? If you installed engram before v1.0.1, it was distributed as a Cask. Uninstall first, then reinstall:

brew uninstall --cask engram 2>/dev/null; brew install gentleman-programming/tap/engram

Windows

Option A: Download the Binary (Recommended)

1. Download the release

   Go to GitHub Releases and download:

   • engram_<version>_windows_amd64.zip (Intel/AMD)
   • engram_<version>_windows_arm64.zip (ARM devices)
2. Extract to PATH

   Extract engram.exe to a folder in your PATH (e.g., C:\Users\<you>\bin\):

   # Extract the archive
   Expand-Archive engram_*_windows_amd64.zip -DestinationPath "$env:USERPROFILE\bin"
   
   # Add to PATH permanently (run once)
   [Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
   
3. Verify installation

   engram version
   

Option B: Install from Source

Requires Go 1.25+:

git clone https://github.com/Gentleman-Programming/engram.git
cd engram
go install ./cmd/engram

The binary is installed to %GOPATH%\bin\engram.exe (typically %USERPROFILE%\go\bin\).

Optional: Build with version stamp (otherwise engram version shows “dev”):

$v = git describe --tags --always
go build -ldflags="-X main.version=local-$v" -o engram.exe ./cmd/engram

Windows notes:

• Data is stored in %USERPROFILE%\.engram\engram.db
• Override with ENGRAM_DATA_DIR environment variable
• All core features work natively: CLI, MCP server, TUI, HTTP API, Git Sync
• No WSL required — it’s a native Windows executable

From Source (macOS / Linux)

Requires Go 1.25+:

git clone https://github.com/Gentleman-Programming/engram.git
cd engram
go install ./cmd/engram

The binary is installed to $GOPATH/bin/engram (typically ~/go/bin/engram).

Make sure $GOPATH/bin is in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Optional: Build with version stamp (otherwise engram version shows “dev”):

go build -ldflags="-X main.version=local-$(git describe --tags --always)" -o engram ./cmd/engram

Download Binary (All Platforms)

Grab the latest release for your platform from GitHub Releases.

Platform	File
macOS (Apple Silicon)	engram_<version>_darwin_arm64.tar.gz
macOS (Intel)	engram_<version>_darwin_amd64.tar.gz
Linux (x86_64)	engram_<version>_linux_amd64.tar.gz
Linux (ARM64)	engram_<version>_linux_arm64.tar.gz
Windows (x86_64)	engram_<version>_windows_amd64.zip
Windows (ARM64)	engram_<version>_windows_arm64.zip

Extract and Install

macOS / Linux

# Extract the archive
tar -xzf engram_*_darwin_arm64.tar.gz

# Make it executable
chmod +x engram

# Move to PATH
sudo mv engram /usr/local/bin/

# Verify
engram version

Windows

# Extract the archive
Expand-Archive engram_*_windows_amd64.zip -DestinationPath "$env:USERPROFILE\bin"

# Add to PATH (if not already done)
[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")

# Verify
engram version

Agent Setup

After installing Engram, connect it to your AI coding agent:

OpenCode

engram setup opencode

For manual configuration or other agents (Antigravity, Cursor, Windsurf), see Agent Setup.

Data Storage

Engram stores all data in a single SQLite database:

macOS / Linux

~/.engram/engram.db

Windows

%USERPROFILE%\.engram\engram.db

Custom Data Directory

Override the default location with the ENGRAM_DATA_DIR environment variable:

macOS / Linux

export ENGRAM_DATA_DIR="/path/to/custom/location"
engram version  # Creates database at /path/to/custom/location/engram.db

Windows

[Environment]::SetEnvironmentVariable("ENGRAM_DATA_DIR", "C:\custom\path", "User")
engram version  # Creates database at C:\custom\path\engram.db

Platform Requirements

macOS

• Minimum OS: macOS 10.15 (Catalina) or later
• Architecture: ARM64 (Apple Silicon) or AMD64 (Intel)
• No dependencies — single binary with no runtime requirements

Install via Homebrew for automatic updates.

Linux

• Minimum kernel: 3.2+
• Architecture: x86_64 (AMD64) or ARM64
• No dependencies — statically linked binary
• No libc required — uses pure Go SQLite implementation

Works on:

• Ubuntu 18.04+
• Debian 10+
• CentOS 7+
• Fedora 28+
• Alpine Linux
• Any modern Linux distribution

Windows

• Minimum OS: Windows 10 or Windows Server 2016
• Architecture: x86_64 (AMD64) or ARM64
• No WSL required — native Windows executable
• No dependencies — single .exe file

All features work natively:

• CLI commands
• MCP server
• TUI (Terminal UI)
• HTTP REST API
• Git Sync

No Dependencies Required

Engram is a single binary with zero runtime dependencies:

• ✅ No Node.js
• ✅ No Python
• ✅ No Bun
• ✅ No Docker
• ✅ No ChromaDB
• ✅ No vector database
• ✅ No worker processes
• ✅ No C libraries (uses pure Go SQLite)

One binary, one SQLite file. That’s it.

Next Steps

Quickstart

Get up and running in 5 minutes

Agent Setup

Connect your AI coding agent

CLI Commands

Learn the command-line interface

Configuration

Customize Engram settings