> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="Homebrew (macOS/Linux)">
    ```bash theme={null}
    brew install gentleman-programming/tap/engram
    ```

    Verify installation:

    ```bash theme={null}
    engram version
    ```
  </Tab>

  <Tab title="Binary Download">
    1. Download the latest release for your platform from [GitHub Releases](https://github.com/Gentleman-Programming/engram/releases)

    2. Extract the binary:

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      tar -xzf engram_*_darwin_arm64.tar.gz
      chmod +x engram
      mv engram /usr/local/bin/
      ```

      ```powershell Windows theme={null}
      Expand-Archive engram_*_windows_amd64.zip -DestinationPath "$env:USERPROFILE\bin"
      [Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
      ```
    </CodeGroup>

    3. Verify installation:

    ```bash theme={null}
    engram version
    ```
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    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:

    ```bash theme={null}
    go build -ldflags="-X main.version=local-$(git describe --tags --always)" -o engram ./cmd/engram
    ```
  </Tab>
</Tabs>

## Agent Setup

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

<CodeGroup>
  ```bash OpenCode theme={null}
  engram setup opencode
  ```

  ```bash Claude Code theme={null}
  claude plugin marketplace add Gentleman-Programming/engram
  claude plugin install engram
  ```

  ```bash Gemini CLI theme={null}
  engram setup gemini-cli
  ```

  ```bash Codex theme={null}
  engram setup codex
  ```

  ```bash VS Code theme={null}
  code --add-mcp "{\"name\":\"engram\",\"command\":\"engram\",\"args\":[\"mcp\"]}"
  ```
</CodeGroup>

<Note>
  For other agents (Antigravity, Cursor, Windsurf) or manual configuration, see [Agent Setup](/agents/overview).
</Note>

## First Memory

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

<Steps>
  <Step title="Save a memory">
    ```bash theme={null}
    engram save "First memory" "Testing Engram memory system. This is my first saved observation."
    ```

    You should see:

    ```
    Saved observation (ID: 1)
    ```
  </Step>

  <Step title="Search for it">
    ```bash theme={null}
    engram search "first memory"
    ```

    You should see your observation in the results with FTS5 ranking.
  </Step>

  <Step title="View statistics">
    ```bash theme={null}
    engram stats
    ```

    You should see:

    ```json theme={null}
    {
      "total_sessions": 1,
      "total_observations": 1,
      "total_prompts": 0,
      "projects": ["default"]
    }
    ```
  </Step>
</Steps>

## 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`:

```typescript theme={null}
{
  "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:

<Steps>
  <Step title="Call mem_search">
    ```json theme={null}
    {
      "query": "N+1 query fix",
      "limit": 5
    }
    ```
  </Step>

  <Step title="Get compact results">
    Results include title, type, project, and a content preview with observation IDs.
  </Step>

  <Step title="Call mem_get_observation (if needed)">
    ```json theme={null}
    {
      "id": 42
    }
    ```

    Gets the full untruncated content.
  </Step>
</Steps>

## Explore the TUI

Launch the interactive terminal UI to browse your memories:

```bash theme={null}
engram tui
```

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

  See [Terminal UI](/features/terminal-ui) for full navigation reference.
</Info>

## What's in Your Database?

Engram stores all data in a single SQLite database:

```bash theme={null}
~/.engram/engram.db
```

On Windows:

```powershell theme={null}
%USERPROFILE%\.engram\engram.db
```

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

## Next Steps

<CardGroup cols={2}>
  <Card title="How It Works" icon="gears" href="/concepts/how-it-works">
    Understand the memory system and session lifecycle
  </Card>

  <Card title="Memory Protocol" icon="book-open" href="/concepts/memory-protocol">
    Learn when agents should save and search memories
  </Card>

  <Card title="MCP Tools" icon="tools" href="/features/mcp-tools">
    Explore all 13 memory tools
  </Card>

  <Card title="Git Sync" icon="code-branch" href="/features/git-sync">
    Share memories across machines and teams
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found: engram">
    Ensure the binary is in your `PATH`.

    **macOS/Linux:**

    ```bash theme={null}
    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:**

    ```powershell theme={null}
    $env:PATH
    where.exe engram
    ```
  </Accordion>

  <Accordion title="Agent doesn't see MCP tools">
    Verify the MCP server is configured:

    **OpenCode:**

    ```bash theme={null}
    cat ~/.config/opencode/opencode.json
    ```

    Should contain:

    ```json theme={null}
    {
      "mcp": {
        "engram": {
          "type": "local",
          "command": ["engram", "mcp"],
          "enabled": true
        }
      }
    }
    ```

    Restart your agent after configuration changes.
  </Accordion>

  <Accordion title="Database locked errors">
    Another Engram process may be running.

    **macOS/Linux:**

    ```bash theme={null}
    ps aux | grep engram
    ```

    **Windows:**

    ```powershell theme={null}
    Get-Process | Where-Object {$_.ProcessName -like "*engram*"}
    ```

    Kill the process and try again.
  </Accordion>
</AccordionGroup>