OpenCode Setup

Full plugin with session tracking and auto-import for OpenCode

Prerequisite: Install the engram binary first via Homebrew or binary download.

One-Command Setup (Recommended)

Installs the plugin AND registers the MCP server automatically:

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

1. Install engram binary

   brew install gentleman-programming/tap/engram
   
2. Run setup command

   engram setup opencode
   
3. Verify installation

   Open OpenCode and check that engram tools are available:

   opencode
   

   Type “list memory tools” and the agent should list mem_save, mem_search, etc.

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:

"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)
  }
}

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

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:

"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:

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

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

Then add the 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:

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

# macOS/Linux
cat ~/.config/opencode/opencode.json | grep engram

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

Server not starting

Manually start the server:

engram serve

Then restart OpenCode.

Next Steps

• Learn about the Memory Protocol
• Explore MCP Tools
• Set up Git Sync for team memory sharing