{"id":16472,"library":"opencode-mem","title":"OpenCode Memory Plugin","description":"OpenCode Memory is a persistent memory system for AI coding agents, providing long-term context retention across sessions using local vector database technology. The package, currently at version 2.13.0, receives frequent minor and patch releases, indicating active development. Key differentiators include its local-first approach using SQLite and USearch (with ExactScan fallback), automated user profile learning, a unified memory-prompt timeline, and a full-featured web UI for management. It supports multi-provider AI (OpenAI, Anthropic) and integrates with over 12 local embedding models, offering intelligent prompt-based memory extraction, smart deduplication, and built-in privacy protection. It acts as an OpenCode plugin, meaning its core functionality is exposed to the AI agent runtime, rather than being directly imported into typical application code.","status":"active","version":"2.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/tickernelz/opencode-mem","tags":["javascript","opencode","plugin","memory","vector-database","ai","coding-agent","local","standalone","typescript"],"install":[{"cmd":"npm install opencode-mem","lang":"bash","label":"npm"},{"cmd":"yarn add opencode-mem","lang":"bash","label":"yarn"},{"cmd":"pnpm add opencode-mem","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an OpenCode plugin and requires the OpenCode AI agent environment to function as its host runtime.","package":"opencode","optional":false},{"reason":"Used for preferred in-memory vector indexing, with an automatic fallback to exact scanning if unavailable. While typically handled internally, its presence affects performance.","package":"USearch"}],"imports":[{"note":"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.","symbol":"memoryPlugin","correct":"import { memoryPlugin } from 'opencode-mem';"},{"note":"TypeScript type for the parameters passed to the `memory()` function that agents interact with, useful for custom tool development or extending functionality.","symbol":"MemoryActionParams","correct":"import type { MemoryActionParams } from 'opencode-mem';"},{"note":"TypeScript union type representing the various 'modes' (e.g., 'add', 'search', 'profile') available for the memory plugin's actions.","symbol":"MemoryAction","correct":"import type { MemoryAction } from 'opencode-mem';"}],"quickstart":{"code":"{\n  \"plugin\": [\n    \"opencode-mem\"\n  ]\n}\n// Save the above JSON to ~/.config/opencode/opencode.json to enable the plugin.\n// After OpenCode restarts, your AI agent can interact with memory.\n\n// Example agent interactions (within an OpenCode session):\n// memory({ mode: \"add\", content: \"Project uses microservices architecture\" });\n// memory({ mode: \"search\", query: \"architecture decisions\" });\n// memory({ mode: \"profile\" });\n// memory({ mode: \"list\", limit: 10 });\n\n// You can also configure the plugin in ~/.config/opencode/opencode-mem.jsonc\n// For example, to set an embedding model:\n// {\n//   \"embeddingModel\": \"Xenova/nomic-embed-text-v1\"\n// }\n","lang":"typescript","description":"Demonstrates how to enable the opencode-mem plugin within OpenCode and provides examples of how an AI agent interacts with its memory functions."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.13.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Add `\"opencode-mem\"` to the `plugin` array in your `~/.config/opencode/opencode.json` file, then restart OpenCode.\nExample: `{ \"plugin\": [\"opencode-mem\"] }`","cause":"The `opencode-mem` plugin has not been correctly added to the OpenCode global configuration file.","error":"Error: Plugin 'opencode-mem' not found in OpenCode configuration."},{"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.","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.","error":"Error: Failed to load embedding model: [model name] / Could not initialize Transformers.js"},{"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.","cause":"The `memoryApiKey` in `opencode-mem.jsonc` is not in one of the supported formats or is missing.","error":"Error: Invalid API Key format. Expected 'sk-...' or 'file://...' or 'env://...'"},{"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.","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.","error":"Log message: 'USearch unavailable, falling back to ExactScan'"}],"ecosystem":"npm"}