
OpenCode Memory: How It Works and How to Add Persistent Memory
AGENTS.md, Compaction, Memory Plugins and MCP for OpenCode v2
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.
| Layer | What it is | Lasts |
|---|---|---|
| Session context | The current conversation | Until the session ends |
| Compaction | A summary of older messages, plus the most recent ones | Inside the session |
| AGENTS.md and instructions | Files you write | Across 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
- Between sessions. A new session starts from AGENTS.md, your instructions and the repository. Decisions made in chat aren’t there.
- After compaction. Older details are reduced to a summary.
- On your other machines. Your global AGENTS.md lives on one computer.
- For teammates. Only what’s committed is shared.
- 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:
| Option | What it is | Best for |
|---|---|---|
| Community memory plugins, such as opencode-mem | Plugins that save and recall context for OpenCode; check that a plugin supports OpenCode v2 | Local memory for OpenCode only |
| Mem0 | Mem0’s OpenCode integration, or its hosted MCP server | Teams already on Mem0 |
| Local MCP memory servers | Basic Memory, the official Knowledge Graph server and others | Memory on one machine |
| Membase | One hosted memory over MCP, shared with your other AI tools | OpenCode 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