@tracemem/opencode-plugin

OpenCode plugin for TraceMem decision tracking and traceability. This plugin provides tools to create, manage, and track decisions through the TraceMem MCP API.

Install

Add the plugin to your opencode.json:

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

OpenCode will automatically install the plugin and its dependencies on startup.

Configure

Required Environment Variable

Set your TraceMem API key:

export TRACEMEM_API_KEY=your_api_key_here

Or add it to your .env file in your project root.

Optional Environment Variable

Override the default MCP server URL (default: https://mcp.tracemem.com):

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

Verify

After installation, verify your setup by asking OpenCode to run:

tracemem_doctor

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

Usage

Recommended Pattern

The recommended workflow for using TraceMem with OpenCode:

1. Open a decision before starting work:

   tracemem_open(action="refactor")
   

2. Add context as you work:

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

3. Read decision data when needed:

   tracemem_decision_read(product="pg_customers_v1", purpose="order_validation", query={"customer_id": "1001"})
   

4. Evaluate a policy:

   tracemem_decision_evaluate(policy_id="discount_cap_v1", inputs={"proposed_discount": 0.15, "customer_tier": "premium"})
   

5. Request approval if needed:

   tracemem_decision_request_approval(title="Discount Approval", message="Customer requesting 25% discount")
   

6. Write mutations to the decision:

   tracemem_decision_write(product="pg_orders_v1", purpose="order_creation", mutation={"operation": "insert", "records": [...]})
   

7. Close the decision when done:

   tracemem_decision_close(action="commit", reason="Order successfully processed")
   

Auto-Intent Mapping

The tracemem_open tool automatically maps common actions to standardized intents:

Action	Intent
edit_files	code.change.apply
refactor	code.refactor.execute
run_command	ops.command.execute
deploy	deploy.release.execute
secrets	secrets.change.propose
db_change	data.change.apply
review	code.review.assist

Example:

tracemem_open(action="refactor")
// Automatically maps to intent: code.refactor.execute

Available Tools

Core Tools

• tracemem_capabilities_get - Get MCP server capabilities
• tracemem_doctor - Verify plugin setup and connection

Product Tools

• tracemem_products_list - List all products
• tracemem_product_get - Get product details

Decision Tools

• tracemem_open - Open a new decision with auto-intent mapping
• tracemem_decision_create - Create a new decision
• tracemem_decision_get - Get decision details
• tracemem_decision_add_context - Add context to a decision
• tracemem_decision_read - Read data through a governed data product
• tracemem_decision_evaluate - Evaluate a policy within a decision context
• tracemem_decision_request_approval - Request approval
• tracemem_decision_write - Write mutation to decision
• tracemem_decision_trace - Get trace information
• tracemem_decision_receipt - Get decision receipt
• tracemem_decision_close - Close a decision

Safe Utilities

• tracemem_note - Add a safe note (automatically sanitized)

State Management

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

Security

Secret Redaction

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

• 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 chars) are truncated, arrays are limited to 100 items, and 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
3. Review before closing - Always review decision data before closing with commit
4. Use appropriate actions - Use abort when work shouldn't proceed, commit when successful

Examples

See the examples/ directory for:

• opencode.json - Example OpenCode configuration
• env.example - Example environment variable configuration

License

Apache-2.0

Repository

https://github.com/tracemem/tracemem-opencode-plugin