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

# Agent Setup Overview

> Choose your AI coding agent and set up Engram persistent memory

Engram works with **any MCP-compatible agent**. The setup varies slightly by agent, but the core pattern is always the same: point your agent's MCP config to `engram mcp`.

## Quick Setup Matrix

<CardGroup cols={2}>
  <Card title="OpenCode" icon="code" href="/agents/opencode">
    Full plugin with session tracking and auto-import
  </Card>

  <Card title="Claude Code" icon="message-bot" href="/agents/claude-code">
    Marketplace plugin with hooks and Memory Protocol skill
  </Card>

  <Card title="Gemini CLI" icon="sparkles" href="/agents/gemini-cli">
    One-command setup with system prompt injection
  </Card>

  <Card title="Codex" icon="terminal" href="/agents/codex">
    Auto-config with compaction recovery
  </Card>

  <Card title="VS Code" icon="code" href="/agents/vscode">
    Native MCP support for Copilot and extensions
  </Card>

  <Card title="Antigravity" icon="rocket" href="/agents/antigravity">
    Google's AI-first IDE with MCP store
  </Card>

  <Card title="Cursor" icon="cursor" href="/agents/cursor">
    Project-level MCP config
  </Card>

  <Card title="Windsurf" icon="wind" href="/agents/windsurf">
    User-level MCP setup
  </Card>
</CardGroup>

## Agent Comparison

| Agent           | Setup Method              | Plugin Available | Auto Session Tracking | Compaction Recovery     |
| --------------- | ------------------------- | ---------------- | --------------------- | ----------------------- |
| **OpenCode**    | `engram setup opencode`   | Yes (TypeScript) | Yes                   | Yes (via hooks)         |
| **Claude Code** | Marketplace               | Yes (bash hooks) | Yes                   | Yes (via hooks)         |
| **Gemini CLI**  | `engram setup gemini-cli` | No               | No                    | Yes (system.md)         |
| **Codex**       | `engram setup codex`      | No               | No                    | Yes (compaction prompt) |
| **VS Code**     | Manual MCP config         | No               | No                    | Manual (instructions)   |
| **Antigravity** | Manual MCP config         | No               | No                    | Manual (GEMINI.md)      |
| **Cursor**      | Manual MCP config         | No               | No                    | Manual (.cursorrules)   |
| **Windsurf**    | Manual MCP config         | No               | No                    | Manual (.windsurfrules) |

## What You Get

### Bare MCP (All Agents)

All agents get access to **14 MCP tools** for persistent memory:

* `mem_save` — Save structured observations
* `mem_search` — Full-text search across memories
* `mem_context` — Get recent session context
* `mem_session_summary` — Save end-of-session summaries
* `mem_update` — Update existing observations
* `mem_delete` — Soft or hard delete memories
* `mem_timeline` — Chronological context around an observation
* `mem_get_observation` — Get full untruncated content
* `mem_suggest_topic_key` — Suggest stable topic keys
* `mem_save_prompt` — Save user prompts
* `mem_capture_passive` — Extract learnings from text output
* `mem_stats` — Memory system statistics
* `mem_session_start` — Register session start
* `mem_session_end` — Mark session as completed

### With Plugins (OpenCode, Claude Code)

Plugins add enhanced functionality:

* **Auto-start** — Starts `engram serve` if not running
* **Session tracking** — Automatic session creation and management
* **Auto-import** — Loads git-synced memories from `.engram/manifest.json`
* **Memory Protocol injection** — Teaches the agent when to save and search
* **Compaction recovery** — Persists context across compaction events
* **Privacy stripping** — Removes `<private>` tags before sending to engram

### With Setup Commands (Gemini CLI, Codex)

The `engram setup` command:

* Registers MCP server in config files
* Writes Memory Protocol to system prompt files
* Configures compaction recovery instructions
* Platform-aware (handles Windows paths automatically)

## Prerequisites

<Warning>
  All agents require the `engram` binary to be installed first.
</Warning>

Install via Homebrew (macOS/Linux):

```bash theme={null}
brew install gentleman-programming/tap/engram
```

Or download from [GitHub Releases](https://github.com/Gentleman-Programming/engram/releases).

See [Installation](/installation) for all platforms.

## Memory Protocol

Without the **Memory Protocol**, agents have the tools but don't know WHEN to use them.

The protocol teaches agents:

* **When to save** — After bugfixes, decisions, discoveries, patterns
* **When to search** — Reactive ("remember") + proactive (overlapping work)
* **Session close** — Mandatory `mem_session_summary` before ending
* **After compaction** — Recover state with `mem_context`

Some agents get this automatically via plugins or setup commands. Others require manual addition to config files.

See each agent's page for specifics.

## Platform Notes

### Windows

* Data stored in `%USERPROFILE%\.engram\engram.db`
* Config paths use `%APPDATA%` (e.g., `%APPDATA%\opencode\`)
* `engram setup` handles Windows paths automatically
* Claude Code plugin hooks require Git Bash or WSL

### macOS

* Data stored in `~/.engram/engram.db`
* Config paths use `~/.config/` or `~/.` prefix
* Install via Homebrew recommended

### Linux

* Data stored in `~/.engram/engram.db`
* Config paths use `~/.config/` or `~/.` prefix
* Install via Homebrew or binary download

## Next Steps

Choose your agent from the cards above to see specific setup instructions.