Skip to content

BuildNot yet confirmed elsewhere1 publisher3 min readPublished

OpenCode has no memory subsystem. It has three mechanisms that fail differently

What OpenCode users call memory is an instruction loader, a SQLite event log and a compaction summarizer. Each has a different owner and a different way of losing your project rule.

The Engineer · Build desk

How we use AISend a correction

Illustration accompanying OpenCode has no memory subsystem. It has three mechanisms that fail differently
Generated illustration

What happened

  • A project that appeared to remember guidance across sessions turned out to have had those Markdown files written by an agent at a user's explicit request, then injected on every turn.
  • No runtime service in OpenCode decides what to save, updates facts when they change, or semantically retrieves them in a later session.
  • The behaviour comes from three mechanisms: instruction files in the system prompt, durable session events in SQLite, and a generated compaction checkpoint.

Why it matters

  • constraint With no embedding index, retrieval path or profile store, nothing carries a fact from one session into the next unless a human or an instructed agent writes it to a file first.
  • decision Anyone whose standing rules sit outside AGENTS.md has to move them before adopting the V2 runtime, or accept that the prompt no longer carries them.
  • exposure After compaction the model is working from a summary nobody ranked, so a rule you can still read in the transcript may no longer be reaching the model that broke it.
  • capability Because the durable layer is inspectable, a bad run can be diagnosed by asking which of the three layers dropped the rule, instead of arguing about what the agent remembered.

The three layers do not fail in the same way, and one word for all of them hides that.

The instruction layer fails by going stale. AGENTS.md, CLAUDE.md and configured instructions are read off disk and placed in the system prompt; the loader reads them and does not maintain them [7]. Nothing notices when a rule stops describing the code, because there is no service that updates facts when they change [5]. A rule that was accurate when it was written is injected with the same authority a year later.

The session layer fails by being read as recall. SQLite holds messages, tool calls, tool results and durable events, while streaming text, reasoning, tool-input and compaction deltas are transient [8]. That makes an old session reopenable and inspectable, and it stops there: the data stays scoped to its session unless another component explicitly reads it [9]. There is no embedding index, no vector retrieval path, no user-profile store and no fact confidence model doing that reading [11].

The working-context layer fails by omission. When a request grows too large, model-visible history is replaced by a generated compaction checkpoint [6], and later requests continue from that checkpoint plus recent context while the old history stays durable in the database [10]. Surviving a long session by summarizing it is not the same as the runtime having picked the important parts [15]. The transcript still contains the constraint you gave early on. The model does not.

The belief that a memory manager exists has a traceable origin. One provider-specific prompt carries a narrow file-memory convention, but core neither manages nor retrieves that file as a memory service [12]. The `/init` command looks like learning and is not: it asks the active agent to create or improve AGENTS.md after the user invokes it [13]. That is close to what produced the case that started the investigation, where guidance sat in Markdown files outside the repository and every new session followed it [3], because an agent had written those files through an ordinary file tool at the user's request and a project-local instructions config loaded them on every provider turn [4].

The delta worth acting on sits in the instruction layer, and it is a shrinkage. The desktop-compatible path under `packages/opencode` accepts four kinds of instruction source: AGENTS.md, optional CLAUDE.md, configured local files, and HTTP instruction sources [14], [1]. The V2 `InstructionContext` under `packages/core` observes AGENTS.md files only [14], which removes three of the four [16]. If your standing rules live in CLAUDE.md or in a file named only in config, the V2 path does not load them, and since the loader has no maintenance duties [7], nothing in the pipeline is responsible for telling you they went missing. The HTTP source in the legacy path is worth a separate look for the opposite reason: it means the system prompt for every turn can include bytes fetched from a remote host [14].

The author is explicit that this reading tracks named files in the current tree, including `session/instruction.ts`, `session/compaction.ts`, `core/src/instruction-context.ts` and `core/src/session/sql.ts` [2], and that where the legacy and V2 paths diverge the difference is called out rather than flattened [1]. That is the right posture for a subsystem that only exists as a habit of speech.

What to watch

  • Whether V2 regains CLAUDE.md, configured local files or HTTP instruction sources before the desktop-compatible path is retired.
  • Whether any component in core starts reading the SQLite session store across session boundaries, which would be the first genuine retrieval path.
  • Whether the provider-specific file-memory convention is promoted into core as a managed and retrieved service.

Clarity's read

What the record supports and how the coverage leans. The claims behind it follow.

Reality

Evidence55
Adoption
Insufficient
Hype gap+12
Incentives28
Confidence48
Why these scores

Claim ledger

Ranked by verification strength, evidence, and original report placement.

  1. [1]

    The article follows the current OpenCode source tree, which contains both the desktop-compatible session path under packages/opencode and the newer V2 runtime under packages/core, and calls out differences between the two paths rather than treating them as one implementation.

  2. [2]

    Primary code references include packages/opencode/src/session/instruction.ts, packages/opencode/src/session/compaction.ts, packages/core/src/instruction-context.ts, packages/core/src/session/context-epoch.ts and packages/core/src/session/sql.ts.

  3. [3]

    The investigation began after the author found a local OpenCode project that appeared to remember guidance across sessions; the guidance lived in Markdown files outside the repository, yet every new session followed it.

    ReportedSupportedView cited source

Sources

1 independent publisher whose own reporting we read for this story.

  1. dev.to

    1 article · August 24, 2026

    OpenCode Memory Internals

Share your take

Let Clarity write the post for you.

Signed-in readers get a short post drafted on this story in the register they choose — narrative, analytical, or a direct position — editable to the last word before it goes anywhere. The share buttons at the top of this story work without an account.

Topics and entities

Follow any of these and your For You feed starts watching them — no settings page required.

Topics

Loading related stories