OpenCode Plugin

Learn how to install and configure the TraceMem OpenCode plugin to enable decision tracking and traceability directly within your OpenCode workflow.

Overview

The @tracemem/opencode-plugin provides a seamless integration between OpenCode and TraceMem's MCP API, enabling you to:

• Track decisions as you work on code changes, refactoring, and deployments
• Automatically map actions to standardized intents for consistent decision tracking
• Add context to decisions throughout your development workflow
• Manage decision lifecycle from creation to closure with built-in tools
• Protect sensitive data with automatic secret redaction and sanitization

This plugin is particularly valuable when working with OpenCode on complex codebases where you need to maintain decision traceability and audit trails for code changes, refactoring, deployments, and other critical operations.

Prerequisites

Before installing the plugin, ensure you have:

1. OpenCode installed - The plugin requires an active OpenCode installation
2. A TraceMem account - Sign up at app.tracemem.com
3. An Agent API key - Generate one from your TraceMem project settings

Installation

Step 1: Install the Plugin

Install the plugin using npm:

npm install @tracemem/opencode-plugin

Step 2: Add Plugin to Configuration

Add the plugin to your opencode.json configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@tracemem/opencode-plugin"]
}

Step 3: Automatic Installation

OpenCode will automatically load the plugin and its dependencies on startup. If you've already installed the package via npm, OpenCode will use the installed version.

Step 4: Verify Installation

After OpenCode restarts, verify the plugin is installed by asking OpenCode to run:

tracemem_doctor

This will check your API key configuration and test connectivity to the TraceMem MCP server.

Configuration

Required Environment Variable

Set your TraceMem API key as an environment variable:

export TRACEMEM_API_KEY=your_api_key_here

Alternatively, add it to your .env file in your project root:

TRACEMEM_API_KEY=your_api_key_here

Important: Never commit your API key to version control. Always use environment variables or secure configuration management.

Optional Environment Variable

Override the default MCP server URL if you're using a custom TraceMem instance:

export TRACEMEM_MCP_URL=https://mcp.tracemem.com

The default URL is https://mcp.tracemem.com, which is suitable for most use cases.

Recommended Workflow

The plugin is designed to work seamlessly with OpenCode's natural workflow. Here's the recommended pattern:

1. Open a Decision

Before starting work on a task, open a decision envelope:

tracemem_open(action="refactor", product_id="your-product-id")

This creates a new decision envelope and sets it as the active decision for subsequent operations.

2. Add Context as You Work

As you make progress, add context to document your decisions:

tracemem_note(kind="info", message="Starting refactoring of user service")

3. Read Decision Data

When you need to review the current decision state:

tracemem_decision_read()

4. Evaluate the Decision

Check if the decision complies with your policies:

tracemem_decision_evaluate()

5. Request Approval (if needed)

If the evaluation requires approval:

tracemem_decision_request_approval()

6. Write Mutations

When making changes that need to be tracked:

tracemem_decision_write(mutation={...})

7. Close the Decision

When work is complete, close the decision:

tracemem_decision_close(outcome="approve")

Auto-Intent Mapping

The tracemem_open tool automatically maps common actions to standardized intents, simplifying decision tracking:

Example

tracemem_open(action="refactor", product_id="my-product")
// Automatically maps to intent: code.refactor.execute

This eliminates the need to manually specify intents for common operations, making decision tracking more intuitive.

Available Tools

The plugin provides a comprehensive set of tools organized by category:

Core Tools

• tracemem_capabilities_get - Get MCP server capabilities and available features
• tracemem_doctor - Verify plugin setup, API key configuration, and connection to TraceMem

Product Tools

• tracemem_products_list - List all products available in your TraceMem project
• tracemem_product_get - Get detailed information about a specific product

Decision Tools

• tracemem_open - Open a new decision with automatic intent mapping
• tracemem_decision_create - Create a new decision envelope with explicit intent
• tracemem_decision_get - Get detailed information about a decision
• tracemem_decision_add_context - Add context data to a decision
• tracemem_decision_read - Read data from a data product within a decision context
• tracemem_decision_evaluate - Evaluate a decision against policies
• tracemem_decision_request_approval - Request approval for a decision
• tracemem_decision_write - Write mutations to a data product within a decision context
• tracemem_decision_trace - Get trace information for a decision
• tracemem_decision_receipt - Get a receipt for a completed decision
• tracemem_decision_close - Close a decision with an outcome

Safe Utilities

• tracemem_note - Add a safe note to a decision (automatically sanitized)

State Management

The plugin maintains the current decision ID in memory for convenience. When you omit the decision_id parameter from decision tools, they automatically use the most recently created decision (from tracemem_open or tracemem_decision_create).

This allows you to work with a decision without repeatedly specifying the decision ID:

tracemem_open(action="refactor", product_id="my-product")
tracemem_note(kind="info", message="Starting work")
tracemem_decision_read()  # Uses the decision from tracemem_open
tracemem_decision_close(outcome="approve")  # Uses the same decision

Security

Secret Redaction

The plugin automatically sanitizes data to prevent secrets from being stored in TraceMem:

• Redacted keys: Any key matching patterns like token, secret, password, api_key, auth, credential, etc. will have their values replaced with [redacted]
• Size limits:
  • Long strings (>1000 characters) are truncated
  • Arrays are limited to 100 items
  • Recursion depth is limited to 10 levels
• Applied to:
  • decision_create.metadata
  • decision_add_context.data
  • decision_read.query
  • decision_write.mutation

Best Practices

1. Never include secrets in metadata or notes - Even though redaction helps, it's better to avoid including secrets entirely
2. Use tracemem_note for safe notes - This tool provides additional safety guarantees beyond automatic redaction
3. Review before closing - Always review decision data before closing with approve outcome
4. Use appropriate outcomes - Use abort or reject when work shouldn't proceed, not just approve

Example Workflow

Here's a complete example of using the plugin during a refactoring task:

1. Start the refactoring:

   textCopy

   tracemem_open(action="refactor", product_id="user-service")
   

2. Document the approach:

   textCopy

   tracemem_note(kind="info", message="Refactoring user service to use dependency injection")
   

3. Read current state (if needed):

   textCopy

   tracemem_decision_read()
   

4. Evaluate the decision:

   textCopy

   tracemem_decision_evaluate()
   

5. Add context as you work:

   textCopy

   tracemem_note(kind="info", message="Extracted user repository interface")
   tracemem_note(kind="info", message="Implemented dependency injection container")
   

6. Close when complete:

   textCopy

   tracemem_decision_close(outcome="approve")
   

Troubleshooting

Plugin Not Available

If the plugin tools don't appear in OpenCode:

1. Verify configuration - Check that @tracemem/opencode-plugin is listed in your opencode.json
2. Restart OpenCode - Fully restart OpenCode to ensure the plugin loads
3. Check installation - Run tracemem_doctor to verify the plugin is properly installed

API Key Issues

If you receive authentication errors:

1. Verify environment variable - Ensure TRACEMEM_API_KEY is set correctly
2. Check key validity - Verify your API key hasn't expired or been revoked
3. Test connection - Run tracemem_doctor to test the connection

Connection Issues

If you're unable to connect to TraceMem:

1. Check network connectivity - Verify you can reach https://mcp.tracemem.com
2. Verify MCP URL - If using a custom URL, ensure TRACEMEM_MCP_URL is set correctly
3. Review logs - Check OpenCode logs for detailed error messages