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

github ↗package ↗

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

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.

import { memoryPlugin } 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.

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

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

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

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 footguns

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.

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.

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.

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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

0 hits · last 30 days

No traffic data recorded yet.

Resources

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

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