# OpenCode Memory

> A persistent memory plugin for AI coding agents that enables long-term context retention across sessions using a local vector database (Turso/libSQL).

OpenCode Memory is an open-source plugin for the OpenCode AI coding platform that gives coding agents a persistent, searchable memory store backed by a local Turso/libSQL vector database. It runs entirely on-device by default, requiring no external vector database service, and supports both automatic background memory capture and manual memory management via a built-in tool API. The project has accumulated over 1,300 GitHub stars and 135 forks since its creation in early 2026.

## What It Is

OpenCode Memory (published as `opencode-mem` on npm) is a plugin that attaches a long-term memory layer to OpenCode coding sessions. When a session goes idle, a background AI request extracts technically meaningful context—architecture decisions, bug patterns, user preferences—and stores it as vector embeddings in a local libSQL database. In later sessions, relevant memories are automatically injected into context, so the agent "remembers" prior work without the user needing to re-explain it.

## How Memory Is Captured and Retrieved

The plugin operates in two modes that can run simultaneously:

- **Auto-capture**: After conversation turns, a background AI request summarizes technical work and saves it as a memory entry. Requires an AI provider that supports structured/tool-call output (e.g., Anthropic Claude, OpenAI GPT-4o-mini).
- **Manual tool calls**: The `memory` tool supports `add`, `search`, `list`, `profile`, `forget`, `list-shards`, `migrate`, `export`, and `import` operations on demand.

Memories are scoped per project (keyed by git remote URL or project root path) or can be queried across all projects with `scope: "all-projects"`. A separate **User Profile** accumulates cross-project preferences and habits, updated automatically on a configurable interval.

## Embedding and Vector Search Architecture

Vector search is powered by libSQL's native `F32_BLOB` column type and `vector_top_k` approximate nearest-neighbor index (DiskANN). No separate vector database or custom SQLite build is required. Embeddings are generated locally by default using `@huggingface/transformers` with ONNX runtime, with the default model being `Xenova/nomic-embed-text-v1` (768 dimensions, multilingual, 8192-token context). Over 12 local embedding models are supported, and a remote OpenAI-compatible embedding endpoint can be substituted via `embeddingApiUrl` and `embeddingApiKey` configuration keys.

Supported local models include:
- `Xenova/nomic-embed-text-v1` — default, multilingual, 768 dims
- `Xenova/jina-embeddings-v2-base-en` — English-only, 768 dims
- `Xenova/all-MiniLM-L6-v2` — very fast, 384 dims
- `Xenova/all-mpnet-base-v2` — high quality, 768 dims

## Web UI and Management

A full-featured web interface is served locally at `http://127.0.0.1:4747` and provides a memory–prompt timeline, capture inspection, and user profile management. When the server is exposed beyond loopback (e.g., `0.0.0.0`), HTTP Basic Auth or a Bearer token (`webServerApiToken`) can be required for all `/api/*` requests. The UI supports re-embed migrations, shard browsing, and export/import workflows.

## Multi-Provider AI Support

Auto-capture and user profile learning work with any provider listed by `opencode providers list`, including Anthropic, OpenAI, GitHub Copilot, and others. The recommended configuration uses `opencodeProvider` + `opencodeModel` so OpenCode owns authentication and token refresh. A manual fallback (`memoryProvider`) supports direct API calls to OpenAI Chat Completions, OpenAI Responses API, Anthropic Messages API, and MiniMax endpoints.

## Update: v2.24.3

The latest release is **v2.24.3**, published on 2026-08-08. Recent development has focused on migrating from legacy SQLite shards to native Turso/libSQL vector format (with automatic migration on first startup, lock files to prevent concurrent migration, and backup preservation), fixing Intel Mac (`darwin/x64`) ONNX runtime teardown crashes by pinning `onnxruntime-node@1.20.1`, and adding the `opencode-mem/tags` public subpath export for third-party plugin interoperability. The project is actively maintained with CI testing across Linux, Windows, macOS 15, and macOS 26 on both Intel and Apple Silicon.

## Features
- Persistent memory across AI coding sessions
- Local Turso/libSQL vector database with native vector search
- Auto-capture: background AI extraction of technical context
- Manual memory tool (add, search, list, forget, migrate, export, import)
- User profile learning across projects
- Full-featured web UI at localhost:4747
- 12+ local embedding models via HuggingFace Transformers/ONNX
- Remote OpenAI-compatible embedding endpoint support
- Smart deduplication
- Multi-provider AI support (OpenAI, Anthropic, GitHub Copilot, MiniMax)
- Project-scoped and cross-project memory search
- Export/import for cross-machine backup and restore
- Shard migration with dry-run and backup preservation
- HTTP Basic Auth and Bearer token for web UI security
- Workspace marker file for multi-repo project memory sharing
- Public subpath exports for third-party plugin interoperability

## Integrations
OpenCode, Anthropic Claude, OpenAI, GitHub Copilot, MiniMax, LiteLLM, HuggingFace Transformers, Turso/libSQL, Bun, npm

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v2.24.3

## Links
- Website: https://github.com/tickernelz/opencode-mem
- Documentation: https://github.com/tickernelz/opencode-mem#readme
- Repository: https://github.com/tickernelz/opencode-mem
- EveryDev.ai: https://www.everydev.ai/tools/opencode-mem