opencode-mem

OpenCode Memory

A persistent memory system for AI coding agents that enables long-term context retention across sessions using local vector database technology.

Visual Overview

Project Memory Timeline:

User Profile Viewer:

Core Features

Local Turso/libSQL database with native vector search, persistent project memories, automatic user profile learning, unified memory-prompt timeline, full-featured web UI, intelligent prompt-based memory extraction, multi-provider AI support (OpenAI, Anthropic), 12+ local embedding models, smart deduplication, and built-in privacy protection.

Prerequisites

This plugin uses embedded Turso/libSQL with native vector indexes (F32_BLOB, vector_top_k). No separate vector database or custom SQLite build is required.

Recommended runtime:

• Bun
• Standard OpenCode plugin environment
• Internet access on first use if you use the default local embedding model, because the model is downloaded by @huggingface/transformers.
• For source/development installs, run bun install before building or testing. The published plugin package installs its runtime dependencies automatically through OpenCode.

CI-tested platforms: Linux, Windows, macOS 15 and macOS 26 on both Intel (darwin/x64) and Apple Silicon (darwin/arm64). Older macOS releases are not excluded by that matrix; they are simply outside the current GitHub-hosted runner set.

Notes:

• Vector embeddings are stored and searched directly in Turso/libSQL; inserts update the vector index automatically.
• Vector search uses libSQL's DiskANN index via vector_top_k (approximate nearest neighbors).
• Auto-capture and user profile learning require an AI provider that can return structured/tool-call output. Memory search/add/list still work without auto-capture provider configuration.

Upgrading from legacy SQLite shards

On first startup after upgrading, opencode-mem automatically migrates existing memory shard databases to native Turso/libSQL vector format:

• Each shard is backed up as .db.legacy.bak before rewrite
• Progress is tracked per shard in .db.turso-migrate.json
• A global marker .turso-migrated is written only after all shards verify successfully
• Do not run multiple OpenCode instances against the same storagePath during migration; a lock file (.turso-migrate.lock) prevents concurrent migration
• Manual dimension migrations use .turso-operation.lock; other plugin processes reject new memory writes until the migration finishes

If migration is interrupted, the next startup resumes from the backup automatically.

If a shard becomes incompatible (for example after changing embeddingDimensions), writes are blocked and the original database is left untouched. Use the Web UI's re-embed migration to build and verify a replacement before it is swapped into place. The previous shard remains available as .db.pre-reembed--.bak.

Getting Started

Add to your OpenCode configuration at ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-mem"],
}

Windows: use %USERPROFILE%\.config\opencode\opencode.json (for example C:\Users\\.config\opencode\opencode.json). This plugin does not read %APPDATA% or %LOCALAPPDATA% for its OpenCode plugin entry — put the file under .config\opencode in your user profile, then restart OpenCode. If the plugin does not appear, confirm that path and restart again.

The plugin downloads automatically on next startup.

How to use day-to-day

You do not need to ask OpenCode to “remember” things for the plugin to work. With the defaults, memory builds up as you work.

Typical daily flow

1. Enable the plugin (see Getting Started) and restart OpenCode.
2. Configure an AI provider for auto-capture — recommended: opencodeProvider + opencodeModel (or "opencodeModel": "inherit"). Details under Auto-Capture AI Provider.
3. Work normally in OpenCode. When a session goes idle, auto-capture extracts memorable technical context and stores it.
4. In later sessions, relevant memories are injected into context (see chatMessage / compaction settings). Browse or edit them in the web UI at http://127.0.0.1:4747.
5. Use the memory tool when you want something stored or retrieved immediately (see Usage Examples).

Automatic vs manual memory

Manual search/add/list still work even if auto-capture has no provider configured. Auto-capture and user profile learning need a provider that can return structured/tool-call output.

Memory vs AGENTS.md / project docs

Rule of thumb: if it is a lasting project instruction, put it in AGENTS.md; if it is context that grows from real work, let memory (or auto-capture) hold it.

Intelligent prompt-based memory extraction

That phrase in the feature list is auto-capture: after a conversation, a background AI request summarizes technical work and saves it as memory. No special prompt from you is required. It uses opencodeProvider / opencodeModel when set, otherwise the manual memoryProvider fallback.

User profile

The User Profile is a separate, cross-project summary of how you like to work (preferences, habits). It is updated on an interval (userProfileAnalysisInterval, default every 10 analyzed prompts), shown in the web UI’s profile view, and readable via memory({ mode: "profile" }). You do not populate it by hand for normal use — profile learning fills it when a provider is ready.

Web UI

Open http://127.0.0.1:4747 to browse the memory–prompt timeline, inspect captures, and manage the user profile. If you bind the server beyond loopback, see Web UI HTTP Basic Auth.

Usage Examples

memory({ mode: "add", content: "Project uses microservices architecture" });
memory({ mode: "search", query: "architecture decisions" });
memory({ mode: "search", query: "architecture decisions", scope: "all-projects" });
memory({ mode: "profile" });
memory({ mode: "list", limit: 10 });
memory({ mode: "list-shards" });
memory({ mode: "migrate", fromPath: "/old/path/to/project" });
memory({ mode: "export", outputPath: "./memories.json" });
memory({ mode: "import", inputPath: "./memories.json" });

Access the web interface at http://127.0.0.1:4747 for visual memory browsing and management.

Network binding security: Keep webServerHost on 127.0.0.1 unless you intentionally expose the UI. Binding to 0.0.0.0 (or any non-loopback host) requires webServerApiToken; all /api/* requests must then send Authorization: Bearer or X-Opencode-Mem-Token. Open the UI with ?apiToken= so the browser stores and sends it.

Dimension migrations generate every new embedding first, import them into a temporary indexed shard, verify the row count, and only then replace the original file. Failed migrations leave the source shard untouched.

Configuration Essentials

Configure at ~/.config/opencode/opencode-mem.jsonc:

Windows: %USERPROFILE%\.config\opencode\opencode-mem.jsonc (same .config\opencode directory as above — not AppData). Default storage resolves to %USERPROFILE%\.opencode-mem\data (the ~ form in the example below expands to your user home on Windows as well).

The plugin creates a full commented template at this path on first startup. This trimmed example shows the most common settings:

…

Choosing / configuring embeddings

Embeddings power similarity search for memories and the user profile. Configure them in the same file (~/.config/opencode/opencode-mem.jsonc). There is no MLX backend — local embeddings use @huggingface/transformers with ONNX, not Apple MLX.

Local (default): set only embeddingModel. On first use the model is downloaded from Hugging Face and cached under {storagePath}/.cache (default ~/.opencode-mem/data/.cache).

Remote (OpenAI-compatible): set both embeddingApiUrl and embeddingApiKey. The plugin then calls {embeddingApiUrl}/embeddings with a Bearer token. embeddingApiKey accepts the same secret formats as memoryApiKey (literal, env://…, file://…).

Recommended local models:

Example — remote OpenAI embeddings:

{
  "embeddingApiUrl": "https://api.openai.com/v1",
  "embeddingApiKey": "env://OPENAI_API_KEY",
  "embeddingModel": "text-embedding-3-small",
}

Changing embeddingModel (or dimensions) can trigger re-embedding of stored memories on next startup. Prefer picking a model once and sticking with it for a given data directory.

Intel Mac (darwin/x64): [email protected] through 1.23.2 can crash OpenCode's embedded Bun 1.3.14 during process exit after successful local embeddings (Ort::Env teardown / SIGILL). The fix shipped in 1.24.1, but fixed releases still lack an x64 native binding. opencode-mem therefore pins [email protected] and loads transformers through a CJS resolve shim so OpenCode nested installs keep that binding. Transformers is resolved to an absolute path before that shim is installed so OpenCode's Bun --compile host does not fail with `Cannot find module '@huggingface/transformer