| name | install-engram |
| description | Install the engram CLI binary and bootstrap a project workspace. Covers all platforms (Linux, macOS, Windows, NixOS) via the one-line installer, direct binary download, nix, or cargo. Also runs the post-install bootstrap sequence (workspace init, agent registration, skills install, commit hook). Use when engram is missing, needs upgrading, or a new project needs initialising. |
Install Engram
Engram is a distributed memory system for AI agents. This skill installs the
engram CLI and optionally bootstraps a project workspace.
Source: https://github.com/vincents-ai/engram
Latest release: https://github.com/vincents-ai/engram/releases/latest
Step 1 — Check if engram is already installed
engram --version
If a version is printed, engram is installed. Skip to Bootstrap if the workspace also needs initialising, or you're done.
If not found, continue to Step 2.
Step 2 — Install the binary
Choose the method that fits the environment.
Recommended: one-line installer (Linux / macOS)
Detects the platform, downloads the right binary, installs to /usr/local/bin
(or ~/.local/bin if no sudo), and optionally runs the bootstrap interactively.
curl -fsSL https://github.com/vincents-ai/engram/releases/latest/download/install.sh | bash
To skip the interactive bootstrap (agent-driven installs):
curl -fsSL https://github.com/vincents-ai/engram/releases/latest/download/install.sh | bash -s -- --no-bootstrap
The installer prompts before every step — it will not apply anything without confirmation.
Manual binary install (when curl is unavailable or you need a specific version)
Download and extract the binary for your platform:
Linux x86_64 (glibc — Ubuntu, Debian, Fedora, Arch, etc.)
curl -L https://github.com/vincents-ai/engram/releases/latest/download/engram-linux-amd64.tar.gz | tar xz
chmod +x engram && sudo mv engram /usr/local/bin/
Linux x86_64 (musl — NixOS, Alpine, containers, static environments)
curl -L https://github.com/vincents-ai/engram/releases/latest/download/engram-linux-musl-amd64.tar.gz | tar xz
chmod +x engram && sudo mv engram /usr/local/bin/
macOS Apple Silicon (M1/M2/M3)
curl -L https://github.com/vincents-ai/engram/releases/latest/download/engram-macos-arm64.tar.gz | tar xz
chmod +x engram && sudo mv engram /usr/local/bin/
macOS Intel
curl -L https://github.com/vincents-ai/engram/releases/latest/download/engram-macos-amd64.tar.gz | tar xz
chmod +x engram && sudo mv engram /usr/local/bin/
Windows x86_64
Download engram-windows-amd64.zip from https://github.com/vincents-ai/engram/releases/latest,
extract it, and add the directory containing engram.exe to your PATH.
Nix / NixOS
Run without installing (for a one-off use):
nix run github:vincents-ai/engram -- --help
Install to your nix profile (persists across shells):
nix profile install github:vincents-ai/engram
Build and run from source with nix:
nix build github:vincents-ai/engram
./result/bin/engram --help
Cargo (build from source)
Requires a Rust toolchain (rustup recommended):
cargo install engram
Or clone and build manually:
git clone https://github.com/vincents-ai/engram.git
cd engram
cargo build --release
sudo cp target/release/engram /usr/local/bin/
Step 3 — Verify the install
engram --version
Expected output: engram X.Y.Z
If engram is not found after install, check your PATH:
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.cargo/bin:$PATH"
Step 4 — Bootstrap the workspace
Run these in the project root. Each command is safe to run on its own — skip any steps that have already been done.
1. Initialise the workspace
Creates .engram/ config in the current directory (git-native storage under refs/engram/):
engram setup workspace
2. Register an agent profile
engram setup agent --name "Claude" --agent-type implementation
engram setup agent --name "Your Name" --agent-type operator
3. Install core engram skills
Installs 14 skills that teach the LLM how to use engram correctly (search-before-acting,
store-everything, orchestration, subagent delegation, etc.):
engram skills setup
4. Install all skills (optional — 44 skills total)
Adds planning, architecture, review, debugging, TDD, compliance, and more:
engram setup skills
5. Install the commit-msg hook (strongly recommended)
Enforces task UUID linkage on every commit — rejects commits without a valid UUID:
engram validate hook install
What each bootstrap step installs
| Step | Command | Output |
|---|
| Workspace | engram setup workspace | .engram/ + config.yaml |
| Agent profile | engram setup agent ... | .engram/agents/<name>.yaml |
| Core skills (14) | engram skills setup | ~/.config/engram/skills/ (or pi skill path) |
| All skills (44) | engram setup skills | same as above, full set |
| Commit hook | engram validate hook install | .git/hooks/commit-msg |
Minimal agent setup (steps 1–3 only)
For a fully functional agent session with no hook enforcement:
engram setup workspace
engram setup agent --name "Claude" --agent-type implementation
engram skills setup
Verifying the workspace
engram validate check
engram ask query "test"
engram next
Troubleshooting
engram: command not found after install
The binary was installed outside your PATH. Run:
./scripts/check-install.sh
or manually check: ls ~/.local/bin/engram, ls /usr/local/bin/engram, ls ~/.cargo/bin/engram
Musl vs glibc: which do I need?
Run ldd --version 2>&1. If it says musl, use the musl binary. If it says GLIBC, use the standard linux-amd64 binary. NixOS always uses musl.
Permission denied moving binary to /usr/local/bin
Install to ~/.local/bin instead:
mkdir -p ~/.local/bin
mv engram ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"
engram setup workspace fails: "not a git repository"
Engram stores data in git refs — the current directory must be a git repo:
git init
engram setup workspace
