Skip to content

INSTALLATION.md

Latest commit

 

History

History
230 lines (177 loc) · 10.9 KB

INSTALLATION.md

File metadata and controls

230 lines (177 loc) · 10.9 KB
Raw

← Back to README

Installation

Choose a release channel before installing

The latest stable release is the production and security-supported line. Release candidates are prerelease validation and feedback builds, not a universal production recommendation or a guaranteed security-supported channel. See the Release Policy for channel, upgrade, and rollback guidance.

Homebrew (macOS / Linux)

brew install gentleman-programming/tap/engram

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

Keep engram serve running across brew upgrade? On macOS, brew upgrade engram replaces the binary and kills any running engram serve process — autosync stops silently until you relaunch it. To make autosync survive upgrades and reboots, use the launchd template in Running as a Service → Using launchd (macOS). Run engram cloud status afterwards: the Local daemon: line should report running.

Windows

Option A: Install via go install (recommended for technical users)

If you have Go installed, this is the cleanest and most trustworthy path — the binary is compiled on your machine from source, so no antivirus will flag it.

Two paths exist because Go's Semantic Import Versioning rule appends /v2 (and above) to the module path starting at major version 2. Pick the line that matches the major version you want:

# Stable line (v1.x — recommended for production; currently tracks @v1.20.0)
go install github.com/Gentleman-Programming/engram/cmd/engram@latest

# v2 line (first post-migration release candidate or any later v2 release)
go install github.com/Gentleman-Programming/engram/v2/cmd/engram@latest
# Binary goes to %GOPATH%\bin\engram.exe (typically %USERPROFILE%\go\bin\)

The /v2 command requires the first release candidate published after this migration, or a later v2 release; existing v2.0.0-rc.1 through v2.0.0-rc.3 cannot use it. @latest selects the latest released version for the requested module path and does not make those earlier RCs compatible. Until then, use the v1 command above or build v2 from a local clone.

Ensure %GOPATH%\bin (or %USERPROFILE%\go\bin) is on your PATH.

Option B: Build from source

git clone https://github.com/Gentleman-Programming/engram.git
cd engram
go install ./cmd/engram
# Binary goes to %GOPATH%\bin\engram.exe (typically %USERPROFILE%\go\bin\)

Want a real version string instead of dev?

go install always stamps the binary as dev. To get a meaningful version, pick one of these — not both. Running them both leaves two binaries on disk and engram version keeps reporting dev because PATH still resolves to the go install build.

Option B1 — version-stamped go install (binary stays on PATH):

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

Option B2 — go build and move the result onto PATH:

$v = git describe --tags --always
go build -ldflags="-X main.version=local-$v" -o engram.exe ./cmd/engram
Move-Item -Force engram.exe "$env:USERPROFILE\go\bin\engram.exe"

After either option, engram version should print local-<git-describe> instead of dev.

Option C: Download the prebuilt binary

  1. Go to GitHub Releases
  2. Download engram_<version>_windows_amd64.zip (or arm64 for ARM devices)
  3. Extract engram.exe to a folder in your PATH (e.g. C:\Users\<you>\bin\)
# Example: extract and add to PATH (PowerShell)
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")

Antivirus false positives on prebuilt binaries

Windows Defender and other antivirus tools (ESET, Brave's built-in scanner) have flagged some engram prebuilt releases as malware (Trojan:Script/Wacatac.H!ml or similar). This is a heuristic false positive. The binary is built reproducibly from the public source code via GoReleaser and contains no malicious code.

Why does this happen? Prebuilt binaries from small open-source projects are unsigned (code signing certificates cost hundreds of dollars per year). Many AV engines automatically flag unsigned executables from unknown publishers, especially recently compiled Go binaries. The same alert has been observed on Claude Code's own MSIX installer, which confirms this is an AV heuristic issue, not a code problem.

Maintainer stance: We will not pay for a code signing certificate at this time. This is a distribution trust problem, not a security problem. The source code is fully auditable.

Recommended workaround: Technical Windows users should prefer Option A (go install) or Option B (build from source). Binaries you compile locally will not trigger AV alerts because they originate from your own machine.

Other 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 for the core binary — it's a native Windows executable

Install from source (macOS / Linux)

Pick the line that matches the major version you want — the /v2 suffix exists starting at major version 2 because of Go's Semantic Import Versioning rule:

# Stable line (v1.x — recommended for production; currently tracks @v1.20.0)
go install github.com/Gentleman-Programming/engram/cmd/engram@latest

# v2 line (first post-migration release candidate or any later v2 release)
go install github.com/Gentleman-Programming/engram/v2/cmd/engram@latest
# Binary goes to $GOPATH/bin (typically ~/go/bin/)

The /v2 command requires the first release candidate published after this migration, or a later v2 release; existing v2.0.0-rc.1 through v2.0.0-rc.3 cannot use it. @latest selects the latest released version for the requested module path and does not make those earlier RCs compatible. Until then, use the v1 command above or build v2 from a local clone.

Or build from a local clone:

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

Want a real version string instead of dev?

go install always stamps the binary as dev. To get a meaningful version, pick one of these — not both. Running them both leaves two binaries on disk and engram version keeps reporting dev because PATH still resolves to the go install build.

Option 1 — version-stamped go install (binary stays on PATH):

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

Option 2 — go build and move the result onto PATH:

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

After either option, engram version should print local-<git-describe> instead of dev.

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

Requirements

  • Go 1.24+ to build from source (not needed if installing via Homebrew or downloading a binary)
  • That's it. No runtime dependencies.

The binary includes SQLite (via modernc.org/sqlite — pure Go, no CGO). Works natively on macOS, Linux, and Windows (x86_64 and ARM64).

Environment Variables

Variable Description Default
ENGRAM_DATA_DIR Data directory ~/.engram (Windows: %USERPROFILE%\.engram)
ENGRAM_PORT 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. 7437
ENGRAM_SOCKET POSIX-only Unix-domain socket path. Run engram serve --socket /path/to/engram.sock (or set ENGRAM_SOCKET) to listen exclusively on the socket; do not combine it with an explicit TCP port. Claude Bash hooks use the same socket when the variable is exported and warn on stderr if socket transport cannot preserve memory capture. PowerShell remains TCP-only. (unset)

Windows Config Paths

When using engram setup, config files are written to platform-appropriate locations:

Agent macOS / Linux Windows
OpenCode ~/.config/opencode/ %APPDATA%\opencode\
Gemini CLI ~/.gemini/ %APPDATA%\gemini\
Codex ~/.codex/ %APPDATA%\codex\
Claude Code Managed by claude CLI Managed by claude CLI
Antigravity CLI ~/.gemini/config/mcp_config.json + ~/.gemini/GEMINI.md %APPDATA%\gemini\config\mcp_config.json + %APPDATA%\gemini\GEMINI.md
Windsurf ~/.codeium/windsurf/mcp_config.json + .../memories/global_rules.md %USERPROFILE%\.codeium\windsurf\...
Qwen Code ~/.qwen/settings.json + ~/.qwen/QWEN.md %USERPROFILE%\.qwen\...
Kiro ~/.kiro/settings/mcp.json + ~/.kiro/steering/engram.md %USERPROFILE%\.kiro\...
Cursor ~/.cursor/mcp.json + ~/.cursor/rules/engram.mdc %USERPROFILE%\.cursor\...
VS Code Copilot ~/.config/Code/User/mcp.json + .../prompts/engram.instructions.md (macOS: ~/Library/Application Support/Code/User/) %APPDATA%\Code\User\...
Kilo Code ~/.config/kilo/opencode.json + ~/.config/kilo/AGENTS.md %USERPROFILE%\.config\kilo\...
Data directory ~/.engram/ %USERPROFILE%\.engram\