OpenCode Memory Plugin

Common errors

• Error: Plugin 'opencode-mem' not found in OpenCode configuration.

  cause The `opencode-mem` plugin has not been correctly added to the OpenCode global configuration file.
  fix Add `"opencode-mem"` to the `plugin` array in your `~/.config/opencode/opencode.json` file, then restart OpenCode. Example: `{ "plugin": ["opencode-mem"] }`

• Error: Failed to load embedding model: [model name] / Could not initialize Transformers.js

  cause The configured `embeddingModel` (e.g., `Xenova/nomic-embed-text-v1`) failed to load, potentially due to network issues, missing local cache, or incompatible environment.
  fix Verify network connectivity if using a remote model. Check that `Bun` (recommended runtime) is properly installed and configured. Try a different, well-tested embedding model. Ensure sufficient disk space and memory for local model caching.

• Error: Invalid API Key format. Expected 'sk-...' or 'file://...' or 'env://...'

  cause The `memoryApiKey` in `opencode-mem.jsonc` is not in one of the supported formats or is missing.
  fix Ensure your API key is correctly specified. Examples: `"sk-..."` for direct keys, `"file://~/.config/opencode/api-key.txt"` for a file path, or `"env://OPENAI_API_KEY"` to read from an environment variable.

• Log message: 'USearch unavailable, falling back to ExactScan'

  cause The preferred `USearch` vector indexing library could not be initialized, often due to native module compilation issues or runtime environment specifics. The plugin defaults to a less performant `ExactScan` method.
  fix While `ExactScan` functions, for optimal performance, investigate the `bun install` logs for any errors related to `USearch` during plugin installation or build. Ensure your system meets any potential native dependency requirements for `USearch` if the issue persists.

Warnings

• breaking Version 2.13.0 included a fix to restore compatibility with the OpenCode 1.3 loader. Older versions of `opencode-mem` (prior to 2.13.0) may have experienced compatibility issues or outright failures when used with OpenCode 1.3. Users on OpenCode 1.3 should ensure they are running `opencode-mem` v2.13.0 or higher.
  Fix: Upgrade `opencode-mem` to version 2.13.0 or newer via `bun install opencode-mem@latest` or `npm install opencode-mem@latest`, and restart OpenCode.
• gotcha Incorrect or incomplete configuration of AI providers or API keys can lead to non-functional memory features. The plugin supports both OpenCode's internal providers (recommended for ease of use) and manual API configurations. Mismatched `opencodeProvider`/`opencodeModel` with `memoryProvider`/`memoryModel`/`memoryApiKey` settings is a common error.
  Fix: Carefully review the `~/.config/opencode/opencode-mem.jsonc` configuration file. Ensure API keys are correctly formatted (e.g., `env://OPENAI_API_KEY`) and that the chosen provider/model combination is valid and has necessary authentication. Use OpenCode's internal providers when possible to simplify authentication.
• gotcha The plugin defaults to `USearch` for vector indexing but includes an automatic fallback to `ExactScan` if `USearch` is unavailable or fails at runtime. While this ensures functionality, `ExactScan` may have significantly lower performance for large memory bases compared to an optimized `USearch` setup.
  Fix: Ensure your environment (especially if running on non-standard systems) supports `USearch` if optimal performance is desired. Check `bun install` or `npm install` logs for any native module compilation errors related to vector indexing libraries. SQLite always remains the source of truth, and indexes are rebuilt from it.
• gotcha OpenCode's plugin loading mechanism means that the `memory()` function is exposed to the AI agent runtime, not typically imported directly by a user's local TypeScript/JavaScript code for execution outside the agent context. Developers wishing to interact with the plugin programmatically or extend it should primarily consider the TypeScript types and the `memoryPlugin` export for integration.
  Fix: Understand the OpenCode plugin architecture. For agent interactions, use the `memory({...})` function as demonstrated in quickstart. For programmatic extension or testing, import specific types or the `memoryPlugin` object directly.

Install

• npm install opencode-mem npm
• yarn add opencode-mem yarn
• pnpm add opencode-mem pnpm

Imports

• memoryPlugin

  import { memoryPlugin } from 'opencode-mem';

  This is the primary plugin export consumed by the OpenCode runtime for registration, not for direct agent interaction. Agents interact via the `memory()` function exposed by OpenCode.
• MemoryActionParams

  import type { MemoryActionParams } from 'opencode-mem';

  TypeScript type for the parameters passed to the `memory()` function that agents interact with, useful for custom tool development or extending functionality.
• MemoryAction

  import type { MemoryAction } from 'opencode-mem';

  TypeScript union type representing the various 'modes' (e.g., 'add', 'search', 'profile') available for the memory plugin's actions.

Quickstart

Demonstrates how to enable the opencode-mem plugin within OpenCode and provides examples of how an AI agent interacts with its memory functions.

{
  "plugin": [
    "opencode-mem"
  ]
}
// Save the above JSON to ~/.config/opencode/opencode.json to enable the plugin.
// After OpenCode restarts, your AI agent can interact with memory.

// Example agent interactions (within an OpenCode session):
// memory({ mode: "add", content: "Project uses microservices architecture" });
// memory({ mode: "search", query: "architecture decisions" });
// memory({ mode: "profile" });
// memory({ mode: "list", limit: 10 });

// You can also configure the plugin in ~/.config/opencode/opencode-mem.jsonc
// For example, to set an embedding model:
// {
//   "embeddingModel": "Xenova/nomic-embed-text-v1"
// }