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

# OpenCode Setup

> Full plugin with session tracking and auto-import for OpenCode

<Note>
  **Prerequisite**: Install the `engram` binary first via [Homebrew](/installation#homebrew-macos-linux) or [binary download](/installation#download-binary).
</Note>

## One-Command Setup (Recommended)

Installs the plugin AND registers the MCP server automatically:

```bash theme={null}
engram setup opencode
```

This does two things:

1. Copies `engram.ts` to `~/.config/opencode/plugins/` (Windows: `%APPDATA%\opencode\plugins\`)
2. Adds the `engram` MCP server entry to `opencode.json`

<Steps>
  <Step title="Install engram binary">
    ```bash theme={null}
    brew install gentleman-programming/tap/engram
    ```
  </Step>

  <Step title="Run setup command">
    ```bash theme={null}
    engram setup opencode
    ```
  </Step>

  <Step title="Verify installation">
    Open OpenCode and check that engram tools are available:

    ```bash theme={null}
    opencode
    ```

    Type "list memory tools" and the agent should list `mem_save`, `mem_search`, etc.
  </Step>
</Steps>

## What the Plugin Provides

The OpenCode plugin is a thin TypeScript adapter that enhances bare MCP:

| Feature                         | Bare MCP | With Plugin |
| ------------------------------- | -------- | ----------- |
| 13 memory tools                 | ✓        | ✓           |
| Auto-start server               | ✗        | ✓           |
| Session tracking                | ✗        | ✓           |
| Auto-import git-synced memories | ✗        | ✓           |
| Memory Protocol injection       | ✗        | ✓           |
| Compaction recovery             | ✗        | ✓           |
| Privacy tag stripping           | ✗        | ✓           |

### Auto-Start Server

The plugin automatically starts `engram serve` if it's not running. No manual `engram serve &` needed.

### Session Tracking

Uses **session resilience** via `ensureSession()`:

* Creates sessions on-demand in engram's database
* Survives plugin reloads and reconnects
* Session IDs come from OpenCode's hook inputs (`input.sessionID`)

### Auto-Import

If `.engram/manifest.json` exists in your project, the plugin runs `engram sync --import` at startup to load git-synced memories.

Clone a repo → open OpenCode → team memories are loaded.

### Memory Protocol Injection

The plugin injects the Memory Protocol via `experimental.chat.system.transform`:

```typescript theme={null}
"experimental.chat.system.transform": async (_input, output) => {
  if (output.system.length > 0) {
    output.system[output.system.length - 1] += "\n\n" + MEMORY_INSTRUCTIONS
  } else {
    output.system.push(MEMORY_INSTRUCTIONS)
  }
}
```

<Info>
  The protocol is **concatenated** into the existing system message, not pushed as a separate one. This ensures compatibility with models that only accept a single system block (Qwen, Mistral/Ministral via llama.cpp).
</Info>

### Compaction Recovery

When OpenCode compacts (summarizes long conversations), the plugin:

1. Auto-saves a session checkpoint
2. Injects context from previous sessions
3. Tells the compressor to instruct the new agent to save memories

Implemented via `experimental.session.compacting` hook:

```typescript theme={null}
"experimental.session.compacting": async (input, output) => {
  // Fetch context from previous sessions
  const data = await engramFetch(`/context?project=${project}`)
  if (data?.context) {
    output.context.push(data.context)
  }
  
  // Tell compressor to remind new agent to persist summary
  output.context.push(
    `CRITICAL INSTRUCTION FOR COMPACTED SUMMARY:\n` +
    `You MUST include: "FIRST ACTION REQUIRED: Call mem_session_summary..."\n`
  )
}
```

### Privacy Stripping

The plugin strips `<private>...</private>` tags before sending to engram:

```typescript theme={null}
function stripPrivateTags(str: string): string {
  return str.replace(/<private>[\s\S]*?<\/private>/gi, "[REDACTED]").trim()
}
```

Double safety: the Go binary also strips, but we strip here so sensitive data never hits the wire.

## Manual MCP-Only Setup (Alternative)

If you only want the 13 memory tools without session tracking:

Add to `~/.config/opencode/opencode.json` (Windows: `%APPDATA%\opencode\opencode.json`):

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

Then add the [Memory Protocol](/concepts/memory-protocol) to your agent prompt manually.

## Platform-Specific Notes

### Windows

`engram setup opencode` writes to:

* Plugin: `%APPDATA%\opencode\plugins\engram.ts`
* Config: `%APPDATA%\opencode\opencode.json`

The server auto-starts in the background. No WSL or Git Bash required.

### macOS / Linux

`engram setup opencode` writes to:

* Plugin: `~/.config/opencode/plugins/engram.ts`
* Config: `~/.config/opencode/opencode.json`

The server auto-starts via `Bun.spawn()`.

## Local Model Compatibility

The plugin works with **all models**, including local ones served via llama.cpp, Ollama, or similar.

The Memory Protocol is concatenated into the existing system prompt (not added as a separate system message), so models with strict Jinja templates work correctly.

## Troubleshooting

### Plugin not loading

Check plugin directory:

```bash theme={null}
# macOS/Linux
ls ~/.config/opencode/plugins/

# Windows
dir %APPDATA%\opencode\plugins\
```

You should see `engram.ts`.

### MCP tools not available

Check `opencode.json` for the engram server entry:

```bash theme={null}
# macOS/Linux
cat ~/.config/opencode/opencode.json | grep engram

# Windows
type %APPDATA%\opencode\opencode.json | findstr engram
```

### Server not starting

Manually start the server:

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

Then restart OpenCode.

## Next Steps

* Learn about the [Memory Protocol](/concepts/memory-protocol)
* Explore [MCP Tools](/features/mcp-tools)
* Set up [Git Sync](/features/git-sync) for team memory sharing