OpenCode Memory

Languages: 🇬🇧 | 🇩🇪 | 🇨🇳 | 🇸🇦 | 🇹🇷 | 🇳🇱

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

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 (@tursodatabase/database) with F32_BLOB vectors and exact cosine search via vector_distance_cos. 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, and macOS 15 / macOS 26 on Apple Silicon (darwin/arm64). Intel Mac (darwin/x64) is not supported — @tursodatabase/database and fixed onnxruntime-node releases ship no x64 native binding. 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; inserts store F32_BLOB vectors for exact cosine ranking.
• Vector search uses exact cosine distance via vector_distance_cos (no DiskANN / approximate index), with optional keyword hybrid ranking when a query string is provided (@tursodatabase/database does not ship FTS5).
• Session lookups use an indexed session_id column (backfilled from metadata.sessionID on schema v2).
• 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.

Hardware / resource expectations

opencode-mem does not require a GPU. Local embeddings run on CPU via @huggingface/transformers and ONNX (there is no MLX backend). Extra VRAM is not needed.

Platform limits above still apply (no Intel Mac darwin/x64; use Apple Silicon, Linux, Windows, or a remote embedding endpoint). See Choosing / configuring embeddings.

Upgrading from legacy SQLite shards

Startup recovers interrupted re-embed swaps, converts libSQL DiskANN indexes to the current Turso engine, and then verifies or upgrades the legacy shard schema. Engine conversion runs even when a store already has a completed legacy migration marker, and preserves stored vectors without re-embedding. Each converted database is backed up as <database>.pre-tursodb-<timestamp>.bak.

On macOS and Linux, multiple OpenCode sessions can share the same storagePath via Turso’s experimental multiprocess_wal (every process must use the same mode — restart all sessions after upgrading). On Windows the engine rejects that flag, so only one OpenCode session can own the memory databases at a time.

tursoMultiprocessWal: false opens in single-owner mode instead: other processes then fail with database is locked rather than sharing the store. That is the safer choice if non-plugin tools touch the same files, because a writing foreign SQLite process makes Turso’s WAL index stale and its own next write is silently lost. tursoAutoHeal (default true) moves a store’s -shm/-tshm index sidecars into storagePath/recovery/<db>-<timestamp>/ and retries once when an open fails with a stale WAL index, after verifying a copy of the main database. A non-empty -wal is never moved, so committed but uncheckpointed transactions survive; only an absent or 0-byte -wal is removed. Concurrent sessions serialise healing through storagePath/recovery/<db>.lock.

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 <shard>.db.legacy.bak before rewrite
• Progress is tracked per shard in <shard>.db.turso-migrate.json
• A global marker .turso-migrated is written only after all shards verify successfully
• Normal inserts and deletes do not invalidate a completed shard migration; startup still checks that its vectors are readable and match its stored dimensions
• 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
• Locks expire after 30 minutes without a progress timestamp update (or file modification time if the timestamp is unavailable), even if the owning process is alive. This lease uses wall-clock time: a forward clock step greater than 30 minutes can expire a progressing operation early; a backward step or future-dated lock can extend an inert lock's life. Locks carry a unique acquisition id, and stale cleanup only removes the exact file it inspected. Migrations heartbeat as they progress and abort if they discover that ownership was lost. Stale-lock cleanup is logged for diagnosis

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 <shard>.db.pre-reembed-<pid>-<timestamp>.bak.

Schema migrations

Local Turso shards and auxiliary databases (metadata.db, user-prompts.db, user-profiles.db, ai-sessions.db) are upgraded with ordered PRAGMA user_version migrations in src/services/turso/schema-migrations.ts. Migrations are idempotent: starting the plugin applies only pending versions.

Getting Started

For OpenCode v2, add the package to the native plugins list:

{
  "plugins": ["opencode-mem@latest"],
}

OpenCode also loads the package's ./tui companion automatically so auto-capture / profile / error toasts render in the TUI (server plugins cannot call ui.toast directly). You do not need a second entry in plugins. If you run a CLI-only TUI against a remote OpenCode server, register opencode-mem/tui in that CLI's plugin list (for example cli.json) so the companion can subscribe to toast RPC events.

For OpenCode v1, add the default entrypoint to your configuration at ~/.config/opencode/opencode.json:

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

With @latest (or a semver range) and autoUpdate: true in opencode-mem.jsonc (default), the plugin clears OpenCode's cached install when a newer npm release is available and asks you to restart. Pinned versions like opencode-mem@2.26.0 are never auto-updated.

Automatic memory context on OpenCode v2

The v2 plugin supplies automatic memory context through the model's system context. These blocks are not added to the authored user prompt or stored in the chat transcript. With chatMessage.injectOn: "first" (the default), the session's initial context is retained across user turns and model steps. With "always", it is refreshed on each authored user turn.

After a host or plugin restart, a resumed session rebuilds its context from the current memory store on its next model request, even if no new user prompt arrives. The rebuilt context may differ from the original as memories and the profile evolve. Restoration does not capture a synthetic user prompt or store a second copy of the memory text in OpenCode plugin storage. Compaction invalidates the cached automatic context; the existing compaction-memory restoration also continues to run.

Using a local checkout

To run the plugin from a local source checkout instead of the npm release, bun install && bun run build