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

Understanding the Workflow

⚠️ CRITICAL: Decision Envelope is MANDATORY

ALL TraceMem operations MUST happen within a decision envelope. This is not optional.

Operations that REQUIRE a decision envelope:

• ✅ tracemem_decision_read - read data
• ✅ tracemem_decision_write - insert/update/delete data
• ✅ tracemem_decision_evaluate - evaluate policies
• ✅ tracemem_decision_request_approval - request approvals

Operations that DO NOT require a decision envelope (discovery tools):

• ❌ tracemem_products_list - list available products
• ❌ tracemem_product_get - get product schema

Attempting any governed operation without a decision envelope will fail with an error.

Core MCP Methods vs Convenience Tools

OpenCode Convenience Tools (plugin-specific):

• tracemem_open → Wrapper for decision_create with action-to-intent mapping
• tracemem_note → Wrapper for decision_add_context with sanitization

Core MCP Tools (always available):

• decision_create, decision_read, decision_write, decision_evaluate
• decision_request_approval, decision_close
• products_list, product_get

Important: Even when using convenience tools like tracemem_open, the same rules apply - ALL operations must occur within the decision envelope created by that call.

What Happens Without a Decision Envelope?

// ❌ WRONG - This will FAIL
await tracemem_decision_read({
  product: "customers_v1",
  purpose: "support_context",
  query: {customer_id: 1001}
});
// Error: "decision_id is required"

// ✓ CORRECT - Create decision first
await tracemem_open({action: "db_change"});
await tracemem_decision_read({
  product: "customers_v1",
  purpose: "support_context",
  query: {customer_id: 1001}
});

Usage

Recommended Pattern

IMPORTANT: ALL operations shown below MUST occur within the decision envelope created in step 1.

The recommended workflow for using TraceMem with OpenCode:

1. Open a decision before starting work (MANDATORY FIRST STEP):

   tracemem_open(action="refactor")

   → Returns decision_id which is automatically saved for subsequent operations

2. Get product metadata before reading/writing (recommended):

   tracemem_product_get(product="customers_v1")

   → Returns METADATA: schema with field names, allowed_purposes, example queries → Does NOT require decision_id → Does NOT return actual data - just information ABOUT the product

3. Add context as you work:

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

   → Uses decision_id from step 1

4. Read actual data when needed (REQUIRES decision_id from step 1):

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

   → Returns ACTUAL DATA: records array with real customer/order/etc data from database → Uses decision_id from step 1 → Use field names from metadata (step 2) → Use purpose from allowed_purposes (step 2)

5. Evaluate a policy (REQUIRES decision_id from step 1):

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

6. Request approval if needed (REQUIRES decision_id from step 1):

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

7. Write data - insert, update, or delete (REQUIRES decision_id from step 1):

   // INSERT - create new record
   tracemem_decision_write(product="orders_v1", purpose="order_creation", mutation={
     operation: "insert",
     records: [{customer_id: 1001, total_amount: 99.99}]
   })
      
   // UPDATE - modify existing record
   tracemem_decision_write(product="orders_v1", purpose="order_update", mutation={
     operation: "update",
     filter: {order_id: 12345},
     data: {status: "shipped"}
   })
      
   // DELETE - remove record
   tracemem_decision_write(product="orders_v1", purpose="data_cleanup", mutation={
     operation: "delete",
     filter: {order_id: 67890}
   })

8. Close the decision when done (MANDATORY FINAL STEP):

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

   → Use "commit" for successful operations → Use "abort" for cancelled/failed operations

Data Flow

Step 1: tracemem_open
   ↓ (returns decision_id, saved automatically)
   
Step 2-7: All operations use the decision_id
   - tracemem_decision_read
   - tracemem_decision_write
   - tracemem_decision_evaluate
   - tracemem_decision_request_approval
   
Step 8: tracemem_decision_close (uses decision_id)

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

Troubleshooting

Error: "decision_id is required"

Cause: You attempted a governed operation without first creating a decision envelope.

Solution: Always call tracemem_open or decision_create FIRST:

// ❌ WRONG
await tracemem_decision_read({product: "customers_v1", ...});

// ✓ CORRECT
await tracemem_open({action: "db_change"});
await tracemem_decision_read({product: "customers_v1", ...});

Error: "invalid automation_mode: manual" (or auto, full_auto, etc.)

Cause: Used an invalid automation mode value.

Valid values (ONLY these 4):

• propose - suggest actions, human decides
• approve - execute after approval
• override - human overrides policy
• autonomous - fully automated

Solution: Use one of the 4 valid values:

// ❌ WRONG
await decision_create({
  intent: "order.create",
  automation_mode: "manual"  // Invalid!
});

// ✓ CORRECT
await decision_create({
  intent: "order.create",
  automation_mode: "autonomous"  // Valid
});

// Or use tracemem_open which sets automation_mode automatically
await tracemem_open({action: "db_change"});

Error: "Purpose 'X' is not allowed for this data product"

Cause: You used a purpose that's not in the product's allowed_purposes list.

Solution: Check allowed purposes FIRST using tracemem_product_get:

// Step 1: Get product info
const product = await tracemem_product_get({product: "customers_v1"});
console.log(product.allowed_purposes);
// Output: ["support_context", "order_validation", "incident_context"]

// Step 2: Use a valid purpose
await tracemem_decision_read({
  product: "customers_v1",
  purpose: "support_context",  // ✓ Valid - from the list
  query: {customer_id: 1001}
});

Error: "field 'customerId' not found in schema"

Cause: Used incorrect field name in query (wrong capitalization or spelling).

Solution: Check product metadata FIRST using tracemem_product_get:

// Step 1: Get product METADATA (not data)
const product = await tracemem_product_get({product: "customers_v1"});
console.log(product.exposed_schema);
// Output: [
//   {name: "customer_id", type: "integer"},  ← Correct field name
//   {name: "name", type: "string"},
//   ...
// ]

// Step 2: Use exact field names from metadata in your query
await tracemem_decision_read({
  product: "customers_v1",
  purpose: "support_context",
  query: {customer_id: 1001}  // ✓ Correct - matches schema
});

Remember:

• product_get → Returns METADATA (schema, purposes) - tells you HOW to use the product
• decision_read → Returns ACTUAL DATA (records) - gives you the real data

Error: "Data product 'X' not found or not accessible"

Cause: Product doesn't exist, is not published, or agent doesn't have access.

Solution: List available products first:

// Check what products are available
const products = await tracemem_products_list();
console.log(products);

// Use an existing product name
await tracemem_decision_read({
  product: "customers_v1",  // ✓ Use exact name from list
  ...
});

Best Practice Checklist

Before performing any data operation:

1. ✅ Create decision envelope - tracemem_open or decision_create
2. ✅ Get product metadata - tracemem_product_get to understand structure (schema, purposes)
3. ✅ Construct operations correctly:
   • Use exact field names from metadata
   • Choose correct write operation: insert (new), update (modify existing), delete (remove)
4. ✅ Use valid purpose - Choose from allowed_purposes list
5. ✅ Close decision - Always call tracemem_decision_close when done

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