Quickstart

Get Engram running in 5 minutes

Get Engram up and running with your AI coding agent in 5 minutes.

Prerequisites

• macOS, Linux, or Windows (x86_64 or ARM64)
• An AI coding agent that supports MCP (OpenCode, Claude Code, Gemini CLI, Codex, VS Code, etc.)
• Go 1.25+ (only if building from source)

Installation

Homebrew (macOS/Linux)

brew install gentleman-programming/tap/engram

Verify installation:

engram version

Binary Download

1. Download the latest release for your platform from GitHub Releases

2. Extract the binary:

macOS/Linux

tar -xzf engram_*_darwin_arm64.tar.gz
chmod +x engram
mv engram /usr/local/bin/

3. Verify installation:

engram version

From Source

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

Optional: Build with version stamp:

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

Agent Setup

Connect Engram to your AI coding agent using the one-command setup:

OpenCode

engram setup opencode

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

First Memory

Let’s verify everything works by saving your first memory using the CLI:

1. Save a memory

   engram save "First memory" "Testing Engram memory system. This is my first saved observation."
   

   You should see:

   Saved observation (ID: 1)
   
2. Search for it

   engram search "first memory"
   

   You should see your observation in the results with FTS5 ranking.

3. View statistics

   engram stats
   

   You should see:

   {
     "total_sessions": 1,
     "total_observations": 1,
     "total_prompts": 0,
     "projects": ["default"]
   }
   

Using with Your Agent

Now that Engram is set up, your agent can use memory tools automatically.

Example: Saving a Memory

When you complete significant work in your coding session, the agent will call mem_save:

{
  "title": "Fixed N+1 query in UserList component",
  "type": "bugfix",
  "content": `
**What**: Added eager loading for user relationships in UserList query

**Why**: List page was making N+1 queries (1 for users + N for each user's profile). Caused 500ms+ page loads with 50+ users.

**Where**: 
- src/components/UserList.tsx (line 45)
- src/api/users.ts (added include: ['profile', 'settings'])

**Learned**: Next.js data fetching doesn't auto-optimize joins. Always check Network tab for N+1 patterns.
  `
}

Example: Searching Memory

When you ask “How did we fix the N+1 query?”, the agent will:

1. Call mem_search

   {
     "query": "N+1 query fix",
     "limit": 5
   }
   
2. Get compact results

   Results include title, type, project, and a content preview with observation IDs.

3. Call mem_get_observation (if needed)

   {
     "id": 42
   }
   

   Gets the full untruncated content.

Explore the TUI

Launch the interactive terminal UI to browse your memories:

engram tui

Navigate with j/k (vim keys), Enter to drill in, t for timeline, / to search, Esc to go back.

See Terminal UI for full navigation reference.

What’s in Your Database?

Engram stores all data in a single SQLite database:

~/.engram/engram.db

On Windows:

%USERPROFILE%\.engram\engram.db

You can inspect it with any SQLite browser or the TUI.

Next Steps

How It Works

Understand the memory system and session lifecycle

Memory Protocol

Learn when agents should save and search memories

MCP Tools

Explore all 13 memory tools

Git Sync

Share memories across machines and teams

Troubleshooting

Command not found: engram

Ensure the binary is in your PATH.

macOS/Linux:

echo $PATH
which engram

If installed via Homebrew, it should be in /opt/homebrew/bin/engram (Apple Silicon) or /usr/local/bin/engram (Intel).

Windows:

$env:PATH
where.exe engram

Agent doesn't see MCP tools

Verify the MCP server is configured:

OpenCode:

cat ~/.config/opencode/opencode.json

Should contain:

{
  "mcp": {
    "engram": {
      "type": "local",
      "command": ["engram", "mcp"],
      "enabled": true
    }
  }
}

Restart your agent after configuration changes.

Database locked errors

Another Engram process may be running.

macOS/Linux:

ps aux | grep engram

Windows:

Get-Process | Where-Object {$_.ProcessName -like "*engram*"}

Kill the process and try again.