opencode-mem

library2.13.0jsnpmunverified

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.

llm-agents vector-search database

npm install opencode-mem

github ↗package ↗

INSTALL

IMPORT

SIG · OPENCODE-MEM

opencode-mem

llm-agentsjavascriptv2.13.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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" // }

Debug

Known issues

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

affects: <2.13.0

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

affects: >=1.0.0

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

affects: >=1.0.0

gotchaOpenCode'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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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://...'

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'

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.

Upgrade

Version history

2.13.0latest on npm

Audit

Dependencies

opencoderequiredThis package is an OpenCode plugin and requires the OpenCode AI agent environment to function as its host runtime.

USearchrequiredUsed for preferred in-memory vector indexing, with an automatic fallback to exact scanning if unavailable. While typically handled internally, its presence affects performance.

Agent activity

120 hits · last 30 days

node

108

OpenAI (training)

Resources

githubhttps://github.com/tickernelz/opencode-mem ↗

packagehttps://www.npmjs.com/package/opencode-mem ↗