OpenCode’s persistent “memory” is a set of files you write and maintain. Put project guidance in an AGENTS.md file in the repository. Put personal, cross-project guidance in ~/.config/opencode/AGENTS.md. Use the instructions config option to pull in other files. The official docs don’t describe an automatic system that recalls every past conversation, so the setup is editable and predictable but not self-updating. Details below follow the OpenCode Rules documentation.
What “memory” means in OpenCode
The documented mechanisms are persistent instructions and reusable configuration. You decide what goes in, you edit it like any text file, and you can review it in version control. The sources I relied on do not establish automatic recall of prior chat history. If you want OpenCode to “remember” something, write it down in one of the files below.
Choosing the right mechanism
| Need | Best fit | Why |
|---|---|---|
| Conventions for one repository | Project AGENTS.md |
Documented as project guidance; the docs recommend committing it so teammates benefit (Rules). |
| Personal conventions across projects | Global ~/.config/opencode/AGENTS.md |
Documented global instruction file (Rules). |
| Reuse existing guides or matching files | instructions in OpenCode config |
Accepts paths and glob patterns; combined with AGENTS.md files (Instructions). |
| Procedure needed only for relevant tasks | Skill with SKILL.md |
Discovered and loaded on demand (Skills). |
| Named specialist with its own prompt or model | Custom agent | Defined as Markdown files or config entries (Agents). |
| Custom tools, hooks, integrations | Plugin | Advanced option; not needed for persistent instructions (Config). |
Setting it up
1. Decide the scope
Ask whether the guidance is about you or about the repository. Personal habits, such as how terse you want answers, belong in the global file. Build commands, layout and team conventions belong in the project file.
2. Write durable, concise guidance
Include what a future session needs and could not easily infer:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches#1 Best Overall
- Commands for building, testing and linting.
- Architecture facts that are not obvious from the code.
- Conventions and style rules.
- Operational gotchas, such as steps that must run in a certain order.
Skip anything the agent can read straight from the code. Short, specific entries are easier to keep accurate.
3. Commit shared guidance
Commit the project AGENTS.md so teammates get the same instructions, as the Rules page recommends. Keep personal preferences in the global file so they don’t leak into the repository.
Rank #2
4. Include existing files with instructions
If you already have a contribution guide or style guide, reference it in your OpenCode config through the instructions option rather than copying it. You can use file paths or glob patterns, and the files are combined with AGENTS.md content. OpenCode also documents remote instruction URLs, fetched with a timeout. Only rely on remote material you trust and that someone maintains, because changes upstream change your agent’s behavior.
5. Move situational procedures into skills
If a behavior is only relevant to certain tasks, such as a release checklist, store it as a SKILL.md in a supported project or global skills directory. OpenCode discovers skills natively and loads them on demand, which keeps your always-on instructions short. See the Skills page for the exact locations.
6. Add a custom agent when you need a specialist
When you want a named profile with its own prompt, and possibly a model preference, define an agent as a Markdown file or config entry. See Agents.
Keeping it maintainable
- Compare the mechanisms on four axes: scope (global or repository), loading (always-on instructions or on-demand skills), reuse (shared conventions or a named agent), and maintenance (one file or references to existing ones).
- Update the file when the agent gets something wrong twice. A correction written into the file persists, and a correction given in chat does not.
- Review changes to
AGENTS.mdin pull requests like any other code.
A caveat on discovery order
The Rules and Instructions pages differ in some details and appear to reflect different documentation versions. This article does not claim one universal discovery or precedence order. Check the current Rules page for the version you run.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
