OpenCode Persistent Memory: A Readable MCP Setup

OpenCode persistent memory should keep the engineering facts that remain useful after a terminal session closes: architecture decisions, failed approaches, deployment constraints, and runbooks. It should not merely preserve every chat turn. Transcripts are evidence; curated knowledge is memory.

For durable project context, your agent's memory should be files you can read, edit, diff, and self-host—not only embeddings inside a retrieval service. Meshnote exposes a plain-markdown wiki through MCP, so OpenCode can maintain it while humans review the same files. Because MCP is model- and client-agnostic, that knowledge can also serve Cursor, Claude Code, Gemini CLI, and other compatible tools.

What the top OpenCode memory results cover

The current leading result, Kronvex's “Persistent Memory for OpenCode via MCP,” gives a local npx MCP configuration, project scoping, five memory tools, verification steps, and instructions that trigger recall at task start and storage at task end. It is a thorough hosted semantic-memory walkthrough.

Codemem's repository takes a local-first route. Its OpenCode plugin captures session events, creates typed memories, combines SQLite FTS5/BM25 with sqlite-vec semantic search, reranks results, and injects a memory pack automatically. It also provides a browser, export/import, and peer-to-peer sync. The opencode-mem repository similarly installs as an OpenCode plugin, but uses embedded Turso/libSQL vector search, automatic capture, profile learning, project shards, and a local management UI.

Those pages explain automatic capture and retrieval well. What they do not provide is a remote OAuth setup whose durable output is an ordinary markdown wiki, plus a repeatable two-session acceptance test and a policy for promoting discoveries into maintainable documentation. That is the gap this guide fills.

Choose the right layer before installing anything

OpenCode already reads AGENTS.md, so use it for concise, always-on rules: build commands, coding conventions, safety boundaries, and where to look for deeper context. Use persistent memory for knowledge that grows during work and should be retrieved selectively. A useful split is:

Repository truth: code, tests, migrations, and checked-in documentation.
Always-on instructions: a short AGENTS.md.
Durable working knowledge: decisions, investigations, source notes, and runbooks in the memory wiki.
Ephemeral context: the current conversation and tool output.

This separation matters because OpenCode's official documentation warns that every MCP server adds tools to the context window. Enable only servers that earn their token cost. For a deeper protocol explanation, see the MCP memory server guide.

Working setup: OpenCode + Meshnote over OAuth

Create a Meshnote project in the web app, then add this project-level file as opencode.json in your repository root. OpenCode merges project configuration with its global configuration, and its current remote-MCP format uses type, url, and enabled:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "meshnote": {
      "type": "remote",
      "url": "https://meshnote.io/mcp",
      "enabled": true
    }
  }
}

Do not add a client ID or secret. OpenCode supports OAuth discovery and Dynamic Client Registration for remote MCP servers; Meshnote supports that flow. Authenticate from the repository:

opencode mcp auth meshnote
opencode mcp list

The first command opens a browser. Sign in and approve the connection; the second should show the server and its authentication state. If discovery fails, run opencode mcp debug meshnote. If your environment cannot open a browser, create a Meshnote API key and use OpenCode's documented headers option with oauth: false; keep the token in an environment variable rather than committing it.

Next, put the lifecycle policy in AGENTS.md. This is intentionally selective rather than “save everything”:

## Project memory
At the start of work, use Meshnote to read the project schema and search
for decisions or runbooks relevant to the task.

After verified work, update memory only for durable knowledge:
- architecture decisions and their rationale
- failed approaches that would otherwise be repeated
- operational constraints and tested runbooks
- stable links to authoritative sources

Do not store secrets, raw transcripts, guesses, or facts already obvious
from the repository. Prefer updating an existing page over creating a duplicate.
Include evidence and the date when a claim may become stale.

This contract keeps retrieval useful and makes review possible. The same governance principle applies when you self-host agent memory: ownership without curation only gives you a private pile of stale context.

Prove persistence with a two-session test

Do not declare memory “working” because a server appears connected. Test a write, end the process, and retrieve from a clean session:

Start OpenCode in the configured repository.
Prompt: “Use Meshnote. List my projects, select the project for this repository, read its schema, and write a page named decisions/api-pagination. Record: ‘Public list endpoints use cursor pagination because inserts made offset pagination unstable.’ Mark this as an acceptance-test decision dated 2026-07-31.”
Ask OpenCode to read the page back. Check the rendered page in Meshnote; inspect the markdown if you run the self-hosted edition.
Exit OpenCode completely.
Start a new session and prompt: “Before editing code, search Meshnote for our pagination decision. State the chosen method and rationale, and cite the page path.”

The test passes only if the second process retrieves cursor pagination, the insert-instability rationale, and the page path. Then delete or relabel the test page if it is not a real project decision. This tests storage, authentication, project selection, retrieval, and provenance—not merely chat continuity. It is the same cross-session standard used in the Cursor agent memory setup.

How the main memory approaches differ

Approach	Best at	Trade-off
AGENTS.md only	Small, mandatory project rules	Always consumes context; poor fit for growing history
Codemem / opencode-mem	Local automatic capture and hybrid or vector recall tightly integrated with OpenCode	Requires extraction, retrieval, and database/plugin operations; raw memory is less natural to review in Git
Mem0 or Zep	Application-facing memory APIs, semantic or graph retrieval, and production agent infrastructure	Excellent when you are building memory into a product; more infrastructure than a team wiki may need
Letta	Stateful agents that actively manage their own context and memory	The agent runtime and memory model are more coupled than an external, tool-agnostic wiki
Native ChatGPT or Claude memory	Personal preferences inside that product	Convenient, but not a shared project knowledge base across coding clients
Meshnote over MCP	Readable, structured markdown knowledge shared across agents and humans	Selective writing and curation require discipline; it is not automatic transcript capture

There is no universal winner. Choose Codemem or opencode-mem when automatic local recall is the priority. Choose Mem0 or Zep when memory is a capability inside your application. Choose Letta when stateful agent behavior is the product. Choose readable MCP memory when auditability, portability, shared ownership, and cross-client use matter most. Hybrid designs are valid: semantic systems can recall episodes while a markdown wiki holds promoted decisions and runbooks.

Operate memory like documentation, not telemetry

Review recently changed pages in code review or a weekly knowledge pass. Require a source for externally verifiable claims. Put dates on temporary constraints. Merge duplicates. Archive superseded decisions rather than letting conflicting pages compete. Never store credentials, customer secrets, or unredacted production data merely because an agent found them.

A practical promotion rule is simple: if forgetting a fact would cause repeated work or a risky decision, and the fact cannot be derived cheaply from the repository, it belongs in durable memory. Everything else can remain in the session log.

Start syncing — $8/mo. Teams that need infrastructure and file ownership can choose Self-hosted for teams from $10/seat/month (minimum five seats).