# opencode-mem: Local Vector Memory for OpenCode

> opencode-mem is an OpenCode plugin that stores coding-agent memories in local Turso/libSQL databases and searches them with exact cosine distance. It suits developers who want persistent project context without operating a separate vector database, subject to native platform limits and AI-provider requirements for automatic capture.

**tickernelz/opencode-mem** — OpenCode plugin that gives coding agents persistent memory using local vector database

- Repository: https://github.com/tickernelz/opencode-mem
- Stars: 1,833 · Forks: 184
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/tickernelz-opencode-mem

## Why opencode-mem adds state to OpenCode

OpenCode agents primarily receive context from the current session. opencode-mem adds a persistence layer for retaining project memories across sessions, which is relevant when an agent needs earlier decisions, user preferences, or coding context to remain available. The intended audience is OpenCode users working with coding agents. It is not a general-purpose vector database for an unrelated application, although its storage layer is designed around vectors and exact cosine search.

The package identifies itself as an OpenCode plugin and publishes entry points for the plugin, server, v2 plugin, terminal UI, and tags service. Its package metadata includes OpenCode plugin and SDK packages, Turso's embedded database, Hugging Face Transformers, and libSQL client packages. This makes it an application-level memory plugin rather than a hosted memory service or a database that must be deployed on another machine.

Memory storage is local under the configured `storagePath`. The default model cache is `~/.opencode-mem/data/.cache`, and the README identifies this path as the cache beneath `~/.opencode-mem/data`. The plugin does not require a GPU. Local embedding generation runs on CPU through `@huggingface/transformers` and ONNX, so its resource cost is primarily RAM, disk space for downloaded models, and CPU execution time. Remote embedding configuration avoids local model memory costs, although the memory database remains local under the configured storage path.

## How Turso vector search stores and recalls memory

opencode-mem stores embeddings directly in embedded Turso databases supplied by `@tursodatabase/database`. Inserts save vectors in the `F32_BLOB` representation. Retrieval uses `vector_distance_cos`, which the README identifies as exact cosine search. It does not use DiskANN or an approximate vector index. That distinction matters when the stored memory collection becomes large. Exact ranking avoids approximation, but the README does not document query latency limits or a maximum practical collection size.

When the caller supplies a query string, the plugin can apply hybrid ranking that combines vector similarity with keyword matching. The keyword component exists because `@tursodatabase/database` does not include FTS5. The available data extends beyond individual memories. The repository describes project memories, an automatically learned user profile, a unified memory-prompt timeline, and AI session data. Session retrieval relies on an indexed `session_id`; schema version 2 backfills this field from `metadata.sessionID` for older records.

Several auxiliary databases are named `metadata.db`, `user-prompts.db`, `user-profiles.db`, and `ai-sessions.db`. The repository implements schema upgrades with ordered `PRAGMA user_version` migrations in `src/services/turso/schema-migrations.ts`, and the README states that pending migrations are idempotent. Automatic memory extraction and user-profile learning require an AI provider capable of structured or tool-call output. By contrast, the README says memory search, memory add, and memory list remain available without auto-capture provider configuration.

## Platform limits for embeddings and Turso storage

The supported environment is narrower than a generic Node.js plugin might suggest. The project lists Linux, Windows, and Apple Silicon macOS in its CI-tested platform matrix, including `macOS 15 / macOS 26 on Apple Silicon (darwin/arm64)`. Intel Mac systems represented by `darwin/x64` are not supported because the README says the required Turso database and fixed `onnxruntime-node` releases have no compatible x64 native binding. A developer using an Intel Mac cannot assume another JavaScript runtime will solve the missing native binding.

The default embedding model is `Xenova/nomic-embed-text-v1`, and the README lists more than 12 local models as available. Local operation does not require extra VRAM, but the documentation estimates about 0.5 to 2 GB of RAM while a local model is loaded, depending on the selected Hugging Face model. First use requires internet access because `@huggingface/transformers` downloads the model. Its cache is commonly hundreds of megabytes or approximately 1 to 2 GB per model. Organizations that prohibit model downloads should examine remote embeddings instead.

Remote embeddings are configured through `embeddingApiUrl` and `embeddingApiKey`. The README describes this path as having negligible local machine-learning RAM usage, although it does not specify supported providers, request limits, or data-retention behavior for the configured endpoint. That silence is material because memory text must reach the embedding service to produce a remote vector. The README also does not enumerate all 12 local model identifiers, so a deployment should not assume that a particular model is included merely from that count.

## Installing opencode-mem and preparing a source checkout

The README identifies the published package as `opencode-mem` and recommends Bun and a standard OpenCode plugin environment. However, it does not give an exact OpenCode command for adding the plugin, a plugin registration snippet, or a first-use command that creates a memory through the user interface. Copying a common OpenCode installation command would risk inventing a flag or configuration key, so this article does not present one. The documented starting point for a published-package installation is the `opencode-mem` package, with registration handled through the user's existing OpenCode plugin setup.

The README specifically says that source and development installations require dependency installation before building or testing. From a local repository checkout, run this command before invoking the build or test scripts:

```bash
bun install
```

The repository contains a `bun.lock` file, so Bun is the dependency tool indicated by the project layout. The install creates the dependencies needed by the TypeScript source and web interface. It does not, by itself, register the plugin with OpenCode.

After dependency installation, the following package script builds the plugin distribution and web application:

```bash
bun run build
```

According to `package.json`, this script removes `dist`, runs `bunx tsc`, and invokes `bun run web:build`. This is useful when developing from source or checking whether the repository's generated files build. The README does not document a CLI command for adding, listing, or searching a memory, so a first OpenCode operation must be performed through the plugin's documented integration surface rather than an invented terminal command.

## Migrations, backups, and concurrent OpenCode sessions

opencode-mem treats a memory database as persistent state that must be migrated carefully. Upgrading from legacy SQLite shards triggers startup work that recovers interrupted re-embedding swaps, converts legacy DiskANN indexes to the current Turso engine, and verifies or upgrades the shard schema. Existing vectors are preserved without re-embedding. The README states that converted databases receive a backup named with the suffix `.pre-tursodb-<timestamp>.bak`.

An older migration path creates `<shard>.db.legacy.bak` files, tracks per-shard progress in `<shard>.db.turso-migrate.json`, and writes the global `.turso-migrated` marker only after every shard verifies. A `.turso-migrate.lock` file prevents multiple OpenCode instances from starting concurrent migrations against the same storage path. An interrupted migration resumes from its backup on the next startup. These safeguards are useful, but they concentrate responsibility in the plugin. Developers should avoid copying or editing its databases while an upgrade is in progress.

On macOS and Linux, multiple OpenCode sessions can share one `storagePath` through Turso's experimental `multiprocess_wal`, provided every process uses the same mode. All sessions must be restarted after upgrading. Windows rejects that flag, so one OpenCode session can own the databases at a time. Changing `embeddingDimensions` can make an existing shard incompatible. In that case, the plugin blocks writes and preserves the original database, leaving the Web UI's re-embed migration to construct and verify a replacement. The prior shard is retained with a `.pre-reembed-<pid>-<timestamp>.bak` suffix.

## Where opencode-mem differs from plain project context

The closest alternative is to place selected project documentation directly into the context supplied to an OpenCode agent. That approach has no vector database, embedding model, schema migration, or database ownership burden. It also gives the developer direct control over what the model sees. Its weakness is retrieval scale. Maintaining a large hand-managed context file becomes cumbersome, and selecting relevant passages remains the user's responsibility.

opencode-mem takes a different approach. It converts stored content into vectors, ranks candidates with exact cosine distance, and can combine that ranking with keyword signals. It is better suited to collecting and retrieving a growing set of remembered interactions, but it introduces a dependency chain involving OpenCode, Turso native bindings, ONNX execution, model downloads, and persistent database migrations. Exact search may become expensive as the memory collection grows, although the repository does not publish a documented dataset limit or latency curve.

The plugin is a poor fit for an Intel Mac, a zero-download environment that cannot use remote embeddings, or a Windows deployment that requires several OpenCode processes to access the same memory databases at once. It is also unsuitable when automatic capture is expected without an AI provider configured for structured or tool-call output. The web UI, user-profile learning, and prompt-based extraction add useful scope, but they also create behavior and state beyond the basic search, add, and list operations.

## Release activity and MIT upgrade responsibilities

The repository is not archived. Its last push was on 2026-10-16, and releases v2.31.0, v2.31.1, and v2.31.2 were published between 2026-10-12 and 2026-10-13. This records recent project activity without implying that every upgrade is free of migration work. The package declares the MIT license, which includes permission to use, copy, modify, merge, publish, distribute, sublicense, and sell copies under the license's conditions. The `LICENSE` file governs those terms.

The maintenance burden is concentrated around native dependencies and persistent state. Upgrading may trigger schema conversion, index replacement, re-embedding recovery, or shard compatibility checks. Database growth follows the number and size of retained memories. Local model selection also affects cache use because each downloaded model can occupy substantial disk space. Developers who change `embeddingDimensions` should not expect an in-place rewrite. The documented design preserves the incompatible shard and moves replacement work into the Web UI migration flow.

Package exports also create upgrade considerations beyond the default plugin entry. The manifest publishes `./server`, `./v2`, `./tui`, and `./tags`, with each entry mapped to compiled files under `dist`. Source installs run TypeScript compilation and a separate web build before creating that distribution. Consumers should verify that the configured version matches the OpenCode plugin entry they intend to load, especially if they depend on one of the secondary exports.

## Conclusion

Developers using OpenCode on Apple Silicon, Linux, or Windows should consider opencode-mem when local persistent memory and inspectable backups matter more than Intel Mac support. Projects that need automatic memory capture must also provide an AI provider capable of structured or tool-call output. Before adoption, verify the host platform, embedding configuration, migration behavior, and the single-session Windows limitation.

## FAQ

### Does opencode-mem require a separate vector database?

No. The README states that the plugin uses embedded Turso from `@tursodatabase/database` and stores `F32_BLOB` vectors there, so a separate database server or custom SQLite build is not required.

### Does opencode-mem work on Intel Macs?

No. The README marks `darwin/x64` as unsupported because the required Turso and fixed `onnxruntime-node` releases have no x64 native binding. Apple Silicon, Linux, and Windows are the documented platform paths.

### Can opencode-mem use remote embeddings?

Yes. Set `embeddingApiUrl` and `embeddingApiKey` to use a remote embedding endpoint. The README says this avoids local machine-learning RAM usage, but it does not document provider limits or endpoint data-retention behavior.

### What happens if a legacy opencode-mem migration is interrupted?

The next startup resumes migration from the backup automatically. The process uses per-shard progress, a lock file, and a global migration marker that is written only after all shards verify successfully.

### Can multiple OpenCode sessions use one opencode-mem storage path?

On macOS and Linux, the README describes shared access through Turso's experimental `multiprocess_wal` when every process uses the same mode. Windows permits only one OpenCode session to own the memory databases at a time.

## Sources

- [Issues](https://github.com/tickernelz/opencode-mem/issues)
- [License: MIT](https://github.com/tickernelz/opencode-mem/blob/main/LICENSE)
- [README](https://github.com/tickernelz/opencode-mem/blob/main/README.md)
- [Releases](https://github.com/tickernelz/opencode-mem/releases)
- [tickernelz/opencode-mem on GitHub](https://github.com/tickernelz/opencode-mem)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tickernelz-opencode-mem