Skip to content
memorylayer.ai Documentation

OpenCode Integration

The MemoryLayer OpenCode plugin (@scitrera/memorylayer-opencode-plugin) gives OpenCode sessions long-term memory that survives context compaction and persists across runs. It pairs the MemoryLayer MCP server (25 tools by default, 38 in the full profile) with proactive hooks tied to OpenCode’s session lifecycle.

What It Does

  • MCP Tools — The same MCP server used by Claude Code, exposing remember/recall/reflect, session management, the context sandbox / RLM, chat threads, and the workspace skills + MCP-server registry helpers.
  • Proactive Hooks — Inject workspace briefings and user directives at session start, recall memories on preference/convention questions, capture tool observations (file edits, searches, commands) as working memory, commit working memory before context compaction, and clean up on exit.
  • Slash Commands — /memorylayer-remember, /memorylayer-recall, /memorylayer-status, /memorylayer-setup.

Prerequisites

The plugin requires a running MemoryLayer server. See Installation for embedding-provider options (embed_server peer, openai, google, or mock):

Terminal window
pip install "memorylayer-server[openai]"
export MEMORYLAYER_EMBEDDING_PROVIDER=openai
export MEMORYLAYER_EMBEDDING_OPENAI_API_KEY=sk-...
memorylayer serve

Installation

Terminal window
npm install @scitrera/memorylayer-opencode-plugin

The plugin pulls in @scitrera/memorylayer-mcp-server as a dependency, so you do not need to install it separately.

Configuration

Add the MCP server and the plugin to your opencode.json:

{
  "mcp": {
    "memorylayer": {
      "type": "local",
      "command": ["npx", "@scitrera/memorylayer-mcp-server"],
      "environment": {
        "MEMORYLAYER_URL": "{env:MEMORYLAYER_URL}",
        "MEMORYLAYER_API_KEY": "{env:MEMORYLAYER_API_KEY}"
      },
      "enabled": true
    }
  },
  "plugin": ["@scitrera/memorylayer-opencode-plugin"]
}

Optional environment overrides:

Terminal window
export MEMORYLAYER_URL=http://localhost:61001
export MEMORYLAYER_API_KEY=your-key
export MEMORYLAYER_WORKSPACE_ID=my-project   # otherwise auto-detected

The workspace ID is auto-detected from:

  1. MEMORYLAYER_WORKSPACE_ID (explicit override)
  2. Git remote origin repo name
  3. Git root directory name
  4. Current working directory name

Verifying

Start OpenCode and run:

/memorylayer-status

You should see the configured URL, detected workspace ID, and the MCP tool count.

Slash Commands

CommandDescription
/memorylayer-remember <content>Store a memory with auto-detected type and importance
/memorylayer-recall <query>Search memories by semantic query
/memorylayer-statusCheck connection status and workspace info
/memorylayer-setupGuided setup and verification

How the Hooks Work

OpenCode hookWhat the plugin does
experimental.chat.system.transformOn first interaction, loads workspace briefing, user directives, and any existing sandbox state into the system prompt.
chat.messageDetects preference, recall, analysis, implementation, and error patterns in user messages and runs targeted recall before the LLM responds.
tool.execute.beforeInjects recalled context for edit/write and task/delegation tools.
tool.execute.afterSilently captures observations (files, facts, concepts, intent) as working memory.
experimental.session.compactingCommits working memory to long-term storage and checkpoints server-side sandbox state before the context window is trimmed.
shell.envPropagates MEMORYLAYER_URL and MEMORYLAYER_API_KEY to shell commands the agent runs.

Architecture

OpenCode
├── MCP Server (@scitrera/memorylayer-mcp-server)
│   └── 25 memory tools by default (38 in `full` profile)
│
├── Plugin Hooks (@scitrera/memorylayer-opencode-plugin)
│   ├── system.transform   → session briefing injection
│   ├── chat.message       → pattern-based recall
│   ├── tool.before        → pre-tool context injection
│   ├── tool.after         → observation capture
│   ├── session.compacting → working memory commit
│   └── shell.env          → env var propagation
│
└── MemoryLayer Server (memorylayer-server)
    ├── Memory storage (SQLite + sqlite-vec)
    ├── Knowledge graph (associations)
    ├── Working memory (sessions)
    └── Context sandbox (Python execution / RLM)

Troubleshooting

Server not reachable

Terminal window
curl http://localhost:61001/health
memorylayer serve   # or run the Docker container

MCP tools not available

Verify opencode.json has the mcp.memorylayer block and restart OpenCode after configuration changes.

Plugin not loading

Ensure the plugin is listed in opencode.json:

{
  "plugin": ["@scitrera/memorylayer-opencode-plugin"]
}