Skip to content
Membase
OpenCode Memory: How It Works and How to Add Persistent Memory

OpenCode Memory: How It Works and How to Add Persistent Memory

AGENTS.md, Compaction, Memory Plugins and MCP for OpenCode v2

Research
MembaseMembase Team
View the original post on Medium

Disclosure: Membase is our product. OpenCode’s built-in instruction files are enough for many projects, and we cover them first. Facts were checked against OpenCode’s v2 documentation in November 2026.

Quick answer

OpenCode doesn’t have a built-in long-term memory that learns across sessions. What carries over is what you write down:

  • AGENTS.md: instructions OpenCode loads at the start of every session, from a global file and every AGENTS.md between your workspace and the project root.
  • Configured instructions: extra files, globs or URLs listed under instructions in opencode.json.
  • CLAUDE.md fallback: if a folder has no AGENTS.md, OpenCode reads CLAUDE.md instead.

Inside one session, OpenCode remembers the conversation, and compaction summarizes older messages so the session can keep going. Once the session ends, anything not written into a file is gone.

To give OpenCode memory that lasts across sessions, machines and tools, add a memory plugin or an MCP memory server. With Membase:

opencode mcp add membase --url https://api.app.membase.com/mcp-http

Does OpenCode have memory?

Not long-term memory in the sense of learning from past sessions.

LayerWhat it isLasts
Session contextThe current conversationUntil the session ends
CompactionA summary of older messages, plus the most recent onesInside the session
AGENTS.md and instructionsFiles you writeAcross sessions, if saved and committed

So in OpenCode, “memory” means files you keep, unless you add a memory layer.

AGENTS.md: memory you write

AGENTS.md is a Markdown file of instructions: build commands, architecture notes, code conventions and checks to run. Run /init in OpenCode to create or update one from your repository.

Where OpenCode looks:

  • Global: ~/.config/opencode/AGENTS.md, for personal rules in every project. It isn’t shared with your team.
  • Project and folders: every AGENTS.md from your current workspace up to the project root. Commit these so your team gets the same guidance.
  • Nested folders: an AGENTS.md deeper in the tree loads when OpenCode reads a file in that area.

Add more files with the instructions field in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"]
}

Configured instructions load after AGENTS.md files, in the order listed. Entries can also be ~/ paths, absolute paths or URLs.

Coming from Claude Code? In any folder without an AGENTS.md, OpenCode reads CLAUDE.md. Without a global ~/.config/opencode/AGENTS.md, it reads ~/.claude/CLAUDE.md. See AGENTS.md vs CLAUDE.md vs SKILL.md.

Good for: stable rules. Not good for: decisions you make while working; OpenCode won’t write them down unless you ask.

Compaction: memory inside a session

When a session approaches the model’s context limit, OpenCode compacts it: it summarizes the conversation and keeps the most recent part, about 15,000 tokens by default, next to the summary so recent details stay exact.

  • Automatic compaction is on by default.
  • Raise compaction.keep.tokens in opencode.json if exact recent details matter.
  • Compaction is lossy. Details from earlier in the session can be dropped.
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "keep": { "tokens": 15000 }
  }
}

Long sessions also get less accurate as they grow; see Context Rot.

Where OpenCode forgets

  1. Between sessions. A new session starts from AGENTS.md, your instructions and the repository. Decisions made in chat aren’t there.
  2. After compaction. Older details are reduced to a summary.
  3. On your other machines. Your global AGENTS.md lives on one computer.
  4. For teammates. Only what’s committed is shared.
  5. In your other AI tools. Claude Code, Codex, Cursor and ChatGPT keep their own memory.

OpenCode memory plugins and MCP servers

OpenCode has a plugin system and connects to MCP servers, so you can add memory either way:

OptionWhat it isBest for
Community memory plugins, such as opencode-memPlugins that save and recall context for OpenCode; check that a plugin supports OpenCode v2Local memory for OpenCode only
Mem0Mem0’s OpenCode integration, or its hosted MCP serverTeams already on Mem0
Local MCP memory serversBasic Memory, the official Knowledge Graph server and othersMemory on one machine
MembaseOne hosted memory over MCP, shared with your other AI toolsOpenCode plus Claude Code, Codex, Cursor and ChatGPT

For a full comparison of MCP memory servers, see Best MCP Memory Servers in 2026.

Add persistent memory to OpenCode with Membase

Membase is a memory layer for AI agents. It keeps one memory outside any single session, machine or tool, so OpenCode can recall decisions from last week and from your other AI tools.

1. Add the server. Remote MCP servers in OpenCode use OAuth by default:

opencode mcp add membase --url https://api.app.membase.com/mcp-http
opencode mcp list

Add --global to make it available in every project.

2. Sign in. If the list shows that the server needs authentication, open OpenCode, run /mcps, select membase and sign in. Create a free account at app.membase.com if you don’t have one.

3. Tell OpenCode to use it. Add one line to your AGENTS.md:

## Memory
- Before starting a task, search Membase for past decisions about this code. Save important decisions to Membase when we agree on them.

4. Test it. Make a decision, end the session, start a new one and ask about it without mentioning it.

What you get:

  • One memory everywhere: the same memory in Claude Code, Codex, Cursor, ChatGPT and Claude.
  • Sources: every search result names where it was learned.
  • Scoped access: keys reach specific memories and can be revoked.
  • Hosted or local: keep memory on your own machine with local mode if you prefer.

Membase is in beta and free during the beta.

Use it alongside AGENTS.md

  • AGENTS.md: Rules that should always apply
  • Compaction: The current session, summarized
  • Membase: Decisions and context that must follow you across sessions, machines, teammates and tools

Frequently Asked Questions

Does OpenCode have memory?
Not long-term memory that learns across sessions. It loads AGENTS.md and configured instructions every session, and compacts long sessions with a summary. Add a memory plugin or MCP server for memory across sessions.
Where does OpenCode store AGENTS.md?
Globally at ~/.config/opencode/AGENTS.md, and in your project: every AGENTS.md from the workspace up to the project root, plus nested files that load when OpenCode reads that area.
Does OpenCode read CLAUDE.md?
Yes, as a fallback. In any folder without an AGENTS.md, it reads CLAUDE.md, and without a global AGENTS.md it reads ~/.claude/CLAUDE.md.
How does compaction work in OpenCode?
Near the context limit, OpenCode summarizes the conversation and keeps about the last 15,000 tokens next to the summary. It’s on by default, and it’s lossy.
What is the best memory plugin for OpenCode?
For memory in OpenCode alone, a community plugin such as opencode-mem. If you’re on Mem0, its OpenCode integration. For one memory across OpenCode and your other AI tools, Membase over MCP.
How do I add an MCP server to OpenCode?
Run opencode mcp add <name> --url <server URL>, then opencode mcp list. Remote servers use OAuth; sign in with /mcps.
Can OpenCode share memory with Claude Code?
They can share rules through AGENTS.md or CLAUDE.md, but not what each learns. Connect both to the same memory server, such as Membase.
Back to all posts