claude-mem-opencode

OpenCode integration for claude-mem persistent memory.

Overview

claude-mem-opencode automatically captures your OpenCode coding sessions as compressed memories, making them searchable for future sessions. It provides persistent context across sessions with ~10x token efficiency compared to storing full tool outputs.

Requirements

• Node.js >= 18.0.0
• Bun >= 1.0.0
• claude-mem >= 8.5.4 (for full functionality)

Important Note

claude-mem v8.5.4 worker API is required for full functionality but is only available from GitHub releases, not npm.

See Installation Guide for detailed instructions on installing claude-mem from GitHub.

Features

• Automatic Memory Capture: Captures tool usage automatically via OpenCode events
• Intelligent Compression: Uses AI to compress observations while preserving context
• Natural Language Search: Search your coding history using natural language
• Privacy Protection: Automatic privacy tag stripping for sensitive data
• Session Mapping: Maps OpenCode sessions to claude-mem sessions
• Context Injection: Automatically injects relevant memories into new sessions

Quick Start

1. Install claude-mem v8.5.4 from GitHub (Required for full functionality)

# Clone claude-mem repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# Build and install
bun install
bun run build
bun link

# Verify installation
claude-mem --version
# Should output: 8.5.4

2. Start claude-mem worker

claude-mem worker start

# Verify worker is running
curl http://localhost:37777/api/health

3. Use in your code

import { ClaudeMemIntegration } from 'claude-mem-opencode'

const integration = new ClaudeMemIntegration()
await integration.initialize()

// Memory is now being captured automatically!

3. Use in OpenCode

import { ClaudeMemIntegration } from 'claude-mem-opencode'

const integration = new ClaudeMemIntegration()
await integration.initialize()

// Memory is now being captured automatically!

// Search memories
const results = await integration.searchMemory("authentication")

// Get project context
const context = await integration.getProjectContext()

// Get status
const status = await integration.getStatus()
console.log(status)

Configuration

The plugin supports flexible configuration through multiple sources:

Configuration Sources (in priority order)

1. Default values - Built-in defaults in the plugin
2. Environment variables - OPENCODE_CLAUDE_MEM_* prefix
3. Global config file - ~/.config/opencode/claude-mem.jsonc
4. Project config file - <project>/.opencode/claude-mem.jsonc

Quick Configuration Examples

# Environment variables
export OPENCODE_CLAUDE_MEM_WORKER_PORT=9999
export OPENCODE_CLAUDE_MEM_DEBUG=true

# Global config file
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/claude-mem.jsonc << 'EOF'
{
  "workerPort": 9999,
  "debug": true,
  "maxContextMemories": 10
}
EOF

# Project config file
mkdir -p .opencode
cat > .opencode/claude-mem.jsonc << 'EOF'
{
  "enabled": false,
  "autoInjectContext": false
}
EOF

Available Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable/disable the plugin | | workerPort | number | 37777 | Port where claude-mem worker is running | | debug | boolean | false | Enable debug logging | | autoInjectContext | boolean | true | Automatically inject context on first message | | maxContextMemories | number | 5 | Maximum memories to inject per session |

For detailed configuration documentation, see Configuration Guide.

Known Issues and Limitations

Current Limitations

2. Project Name Extraction Edge Cases

• Severity: Low
• Impact: Nested paths return filename instead of directory name
• Details: Simple basename extraction doesn't walk directory tree
• Workaround: Use current directory (works correctly)
• Affected scenarios: Importing from non-current paths

3. Integration Tests Require OpenCode Runtime

• Severity: Informational
• Impact: Some test scenarios require OpenCode to actually load the plugin
• Details: Direct API testing completed successfully (11/11 tests passed)
• Affected: Context injection, tool hooks, event hooks
• Resolution: Tests will verify when plugin is loaded in OpenCode

Installation Tips

Worker Version: Requires claude-mem v8.5.4 or higher from GitHub releases

• Reason: npm package (v3.9.16) doesn't include worker API needed by this plugin
• Solution: Install from source or wait for npm update

Plugin Installation:

• Add to opencode.jsonc: {"plugin": ["claude-mem-opencode"]}
• Ensure claude-mem worker is running before starting OpenCode
• Verify plugin loads: Look for [CLAUDE_MEM] messages on startup

Troubleshooting Quick Reference

| Issue | Solution | |-------|----------| | Plugin not loading | Check opencode.jsonc syntax, restart OpenCode | | Worker not responding | Run claude-mem worker restart, check port 37777 | | No context injected | Verify memories exist for project, check worker logs | | Tool not available | Check plugin loaded, check for tool in OpenCode tool list |

API Reference

new ClaudeMemIntegration(workerUrl?: string)

• workerUrl: Optional URL of claude-mem worker (default: http://localhost:37777)

Methods

initialize(): Initialize the integration

await integration.initialize()

getStatus(): Get integration status

const status = await integration.getStatus()
// Returns: { initialized, workerReady, workerUrl, currentProject }

getProjectContext(project?): Get memory context for a project

const context = await integration.getProjectContext('my-project')

searchMemory(query, options?): Search memories

const results = await integration.searchMemory('authentication', {
  limit: 10,
  type: 'code',
  project: 'my-project'
})

isMemoryAvailable(): Check if memory features are available

if (integration.isMemoryAvailable()) {
  // Memory operations available
}

getWorkerClient(): Get underlying WorkerClient (advanced usage)

const client = integration.getWorkerClient()
await client.initSession({ ... })

shutdown(): Shutdown integration

await integration.shutdown()

WorkerClient

Low-level HTTP client for claude-mem worker API.

import { WorkerClient } from 'claude-mem-opencode'

const client = new WorkerClient(37777)

// Check health
await client.healthCheck()

// Initialize session
await client.initSession({
  contentSessionId: 'session-123',
  project: 'my-project',
  prompt: 'Initial prompt'
})

// Add observation
await client.addObservation({
  sessionDbId: 1,
  promptNumber: 1,
  toolName: 'bash',
  toolInput: { command: 'ls' },
  toolOutput: 'file1.txt\nfile2.txt',
  cwd: '/home/user/project',
  timestamp: Date.now()
})

// Complete session
await client.completeSession(1)

// Search
const results = await client.search('query', { limit: 10 })

EventListeners

Listens to OpenCode events and captures tool usage.

import { EventListeners } from 'claude-mem-opencode'

const listeners = new EventListeners(workerClient)
await listeners.initialize()

ContextInjector

Injects memory context into OpenCode sessions.

import { ContextInjector } from 'claude-mem-opencode'

const injector = new ContextInjector(workerClient)
const context = await injector.injectContext('my-project')

SessionMapper

Maps OpenCode session IDs to claude-mem session IDs.

import { SessionMapper } from 'claude-mem-opencode'

const mapper = new SessionMapper()

// Map sessions
mapper.mapOpenCodeToClaudeMem('opencode-session-123', 1)

// Get mapping
const claudeMemId = mapper.getClaudeMemSessionId('opencode-session-123')

PrivacyTagStripper

Removes privacy tags from content before storage.

import { PrivacyTagStripper } from 'claude-mem-opencode'

const stripper = new PrivacyTagStripper()

const cleaned = stripper.strip('<private>secret</private> data')
// Returns: ' data'

ProjectNameExtractor

Extracts project name from directory paths.

import { ProjectNameExtractor } from 'claude-mem-opencode'

const extractor = new ProjectNameExtractor()

const projectName = extractor.extract('/home/user/my-project')
// Returns: 'my-project'

const currentProject = extractor.getCurrentProject()
// Returns: name of current working directory

Logger

Simple logging utility.

import { Logger, LogLevel } from 'claude-mem-opencode'

const logger = new Logger('MY_APP')

logger.debug('Debug message')
logger.info('Info message')
logger.warn('Warning message')
logger.error('Error message')

Privacy Protection

Use privacy tags to prevent sensitive data from being stored:

// This will not be stored
<private>password = "secret123"</private>

// This will not be stored
<claude-mem-context>Previously injected context</claude-mem-context>

The PrivacyTagStripper automatically removes these tags before storing data.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      OpenCode                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐│
│  │    Bus       │  │   Session    │  │  MessageV2   ││
│  │  (Events)    │  │   (Info)     │  │   (Part)     ││
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘│
│         │                 │                 │          │
│         └─────────────────┴─────────────────┘          │
│                           │                             │
│                    claude-mem-opencode                │
│                           │                             │
└───────────────────────────┼─────────────────────────────┘
                             │ HTTP
                     ┌───────▼────────┐
                     │ claude-mem     │
                     │ Worker API     │
                     │ (localhost:    │
                     │  37777)        │
                     └────────────────┘

Development

Building

npm run build

Testing

# Run all tests
npm test

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

Creating Bundle

npm run bundle

Testing

Run unit tests (no claude-mem required):

npm run test:unit
# Expected: 54 pass

Run integration/E2E tests (requires claude-mem worker):

# Start worker
claude-mem worker start

# Run tests
npm run test:integration
npm run test:e2e

# Stop worker
claude-mem worker stop

See Testing Guide for comprehensive testing instructions.

Troubleshooting

Worker not starting

# Verify claude-mem installation
claude-mem --version
# Must be 8.5.4 or higher

# Check worker logs
claude-mem worker logs

# Ensure port 37777 is available
lsof -i :37777  # macOS/Linux

License

MIT

Project Status

Overall Progress: ~78% Complete

Phase Summary

| Phase | Status | Details | |-------|--------|---------| | Phase 1: Architecture Refactor | ✅ COMPLETE | Production-ready plugin using official OpenCode API | | Phase 2: Testing | ✅ COMPLETE | All core features verified (11/11 tests passed) | | Phase 3: Configuration System | ✅ COMPLETE | Flexible config system with env vars and JSONC files | | Phase 4: Documentation | ✅ COMPLETE | Comprehensive user and developer documentation | | Phase 5: Advanced Features | ❌ NOT STARTED | | | Phase 6: Cleanup | ✅ COMPLETE | Removed obsolete files and updated documentation | | Phase 7: Polish | ❌ NOT STARTED | |

Current State

✅ Working Features:

• Session lifecycle management (OpenCode ID ↔ claude-mem ID)
• Automatic context injection on first message
• Tool usage capture with privacy protection
• Manual memory operations via claude-mem tool
• Flexible configuration system (env vars, global config, project config)
• Fail-hard worker initialization
• Project name extraction
• Privacy tag stripping

⚠️ Known Limitations:

• Integration tests require OpenCode runtime (direct API tests completed)
• Project name extraction edge cases for nested paths

📚 Documentation:

• Installation Guide: Step-by-step setup instructions
• Usage Guide: Comprehensive examples and workflows
• API Reference: WorkerClient and integration classes
• Development Summary: This section

Installation Quick Start

# 1. Install claude-mem v8.5.4 from GitHub
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
bun install
bun run build
bun link

# 2. Start claude-mem worker
claude-mem worker start

# 3. Install plugin (when published)
npm install -g claude-mem-opencode

# 4. Add to OpenCode config
# Edit ~/.config/opencode/opencode.jsonc
{
  "plugin": ["claude-mem-opencode"]
}

For Developers

The plugin is functional and ready for use. All integration components use the official OpenCode plugin SDK with proper TypeScript types.

License

MIT

Acknowledgments

• claude-mem - Persistent memory for Claude Code
• OpenCode - The AI CLI