OpenCode Memory: Persistent Context Setup Guide

OpenCode starts every session with an empty context window. Here is how to give OpenCode memory that survives /clear, restarts, and new terminals — and how to verify it actually recalls your project.

Why OpenCode sessions lose context

Every OpenCode session starts with an empty context window. The conventions you settled on last week — test runner, naming rules, the fact that the API client retries on 429 — live in the transcript, and the transcript is not what the model sees tomorrow. Close the session or run /clear, and that context is gone.

A larger window does not solve this: it is working memory, holding the current conversation and rewritten as that conversation grows or is compacted. A memory layer is separate storage that outlives the session. That separation is OpenCode memory: facts that survive the transcript instead of living inside it. Without it, the agent relearns your project every morning, and you pay in repeated instructions. Why your coding agent forgets conventions covers the underlying pattern.

OpenCode is extensible, which means you can fix it without changing how you work. Install one npm package, connect a key, and every prompt starts with the facts that mattered in earlier sessions.

Two kinds of context behave differently. Session state — open files, the current branch, the last failing test — is cheap to rebuild and changes hourly. Durable context is the expensive part: why the team dropped a library, which migration is already half-applied, what the deployment runbook assumes. A fresh context window cannot reconstruct any of it. Holding that durable half is the job of a memory layer.

Install the OpenCode memory plugin

Install the plugin globally:

npm install -g @audaxic/memory-opencode

Register it in your opencode.json so OpenCode loads it at startup:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@audaxic/memory-opencode"]
}

Before the plugin can save anything, it needs a project key that starts with ak_. Run the setup command and paste a key from your dashboard:

npx @audaxic/memory-opencode setup

The OpenCode plugin docs cover the optional TUI sidebar, the environment-variable alternative, and what to check when the plugin does not load. If you would rather create the key and make your first call yourself, the REST quickstart walks through the API directly.

Restart OpenCode after registering the plugin. From then on the plugin is passive: it saves as you work and searches before answers, with no command to run and no prompt to paste. For the optional TUI sidebar, register the same package in the TUI config as well.

How the plugin saves and recalls memories

As you chat, the plugin captures your prompts and the assistant's answers and sends them to POST /add at https://api.memory.audaxic.com. Audaxic extracts discrete memories from each batch, and every extracted memory counts as one add request. A single /add call that produces five memories counts as five adds, which is why the metric to watch is extracted memories rather than chat messages.

Extraction happens server-side, so you do not curate memories by hand. The billing unit is one extracted memory, not a chat message and not an API call. A retrieve is a search or list call; the memories it returns are counted in groups of ten.

Before the agent answers a new prompt, the plugin searches with POST /search and injects the relevant memories into that request. Your OpenCode memory grows as a side effect of ordinary work rather than a manual "remember this" ritual. Injected context is scoped to the request, so it does not rewrite the session transcript or masquerade as something you typed.

What survives is the useful part: preferences ("use pnpm, not npm"), decisions ("auth moves to the edge middleware"), and constraints ("the staging database resets nightly"). Storage is isolated per organization with namespace-scoped vector search, so two projects on one account do not bleed into each other, and customer data is never used for training. Graph memory is included on every plan, from Hobby through Enterprise, so relationships between facts are part of the default product rather than a separate add-on.

Connect OpenCode through the MCP server instead

If you do not want a package in the loop, or you want the same memory in several agents, use the remote MCP server. The endpoint is https://memory-mcp.audaxic.com/mcp; it speaks Streamable HTTP and authenticates with a Bearer ak_... key. Client-by-client instructions are in the MCP setup docs.

The tradeoff is who decides. The plugin saves and recalls without the model choosing to, so it works even when the agent is focused on a narrow task. MCP hands the decision to the model: the agent calls the memory tools when it judges them useful, which is more flexible and slightly less predictable. Both paths write to the same account, so you can run the plugin in OpenCode and MCP in a client like Claude Desktop or Windsurf without splitting your context. Cursor connects through MCP only — there is no Cursor plugin.

The MCP route also fits mixed setups. One server URL can be registered in every MCP-capable client you use, and memories collected by a desktop client land in the same account your OpenCode plugin reads. If your team standardizes on MCP, keep the plugin for automatic capture in OpenCode; the two are not mutually exclusive.

Import past OpenCode conversations

Installing the plugin today leaves months of older context out. The importer reads the history each CLI keeps on disk and sends it to your account with the correct timestamps, so old decisions become searchable alongside new ones. Install it once:

npm install -g @audaxic/memory-import

Preview the OpenCode import before sending anything:

audaxic-memory-import --tool opencode --dry-run

For OpenCode, the importer reads ~/.local/share/opencode/opencode.db and imports user and assistant text; tool calls, reasoning blocks, and system prompts are skipped. Processed messages are tracked in a state file, so re-running the importer picks up new conversations and skips what is already stored. Start with the dry run, check the message counts, then run the same command without the flag. The full walkthrough covers Claude Code and Codex as well.

The importer is also the fastest way to make a new install useful on day one. Without it, recall only covers conversations that happened after setup, and the first week of a memory layer feels thin. With it, the agent can answer questions about work you finished months ago, because old messages arrive with their original days attached instead of as one undated blob.

Verify recall and tune what gets stored

Verification takes two minutes. Start a fresh OpenCode session and ask something only an earlier session would know — the package manager you chose, the internal service name, or why a dependency is pinned. If the answer is right without you restating it, recall works. You can also open the dashboard and check what is stored; the list endpoint is paginated, so browse rather than scroll forever. Data-plane calls use the project key and a date-based X-Api-Version header, currently 2026-09-25.

Recall is not read-only. When a stored memory is wrong or stale, fix it rather than re-explaining: PUT /update changes a memory in place, and DELETE /delete/{memory_id} removes one. Checking what the layer holds is the fastest way to spot a bad extraction, and it beats waiting for a bad answer to surface it.

Then tune the economics. Hobby is $0/month with 10,000 adds and 1,000 retrieves; Starter is $12/month for 50,000 adds and 5,000 retrieves. Every plan from Hobby through Enterprise includes graph memory and unlimited projects, and paid tiers bill flat — no per-token fees and no overages. If your add count climbs because sessions run long, the counting rule above tells you exactly why.

OpenCode memory is not a bigger context window; it is storage that outlives one. If a session still loses detail mid-task, that is compaction of the context window, a separate problem from recall — the compaction walkthrough explains what gets rewritten and when.

FAQ

Written by Efe — Sep 25, 2026 · More articles · X @AudaxicTech