Model: openai/gpt-5.4 Generated: 2026-04-01 Book: Claude Code VS OpenCode: Architecture, Design and The Road Ahead Chapter: 8 — Configuration and Customization Token Usage: N/A (runtime does not expose per-file token counts)
8.2 Project Memory System
Configuration tells an agent how to behave before a session starts. Memory tells it what should persist after the session ends. In modern coding agents, memory is no longer just “chat history.” It is a structured persistence layer for conventions, context, and learned collaboration patterns.
All three systems in this book share one foundational convention: markdown files such as CLAUDE.md, AGENTS.md, and README.md serve as a human-readable knowledge base. This convention matters because it bridges two audiences at once: humans can edit the files directly, and agents can ingest them as instruction context.
Shared convention: project markdown as durable context
The common pattern across OpenCode, Claude Code, and OMO is that project knowledge is stored in plain text files checked into, or adjacent to, the repository. README.md explains the project to humans first, but it is also useful agent context. CLAUDE.md and AGENTS.md are more agent-oriented: they encode rules, conventions, workflows, and local expectations.
This is significant because it represents a move away from opaque memory. Instead of hiding all persistence inside a database, these systems externalize key parts of memory into artifacts that developers can inspect, diff, review, and version.
Claude Code: a typed memory model
Claude Code goes furthest in formalizing memory as a taxonomy. In src/memdir/memoryTypes.ts, it defines four memory types:
userfeedbackprojectreference
This is a powerful design choice because it narrows what “memory” is allowed to mean.
user memory stores facts about the user’s role, preferences, and expertise. feedback memory stores guidance about how Claude should work with the user or the team. project memory captures ongoing work, deadlines, goals, and incidents that are not directly derivable from the codebase. reference memory stores pointers to external systems such as dashboards, ticket trackers, or documentation.
Just as important is what Claude Code explicitly forbids saving. The memory rules state that code patterns, architecture, file paths, git history, and information already present in CLAUDE.md should not be stored as memory. That distinction is crucial. Memory is reserved for non-derivable context, not for facts the agent can simply re-read.
Claude Code also supports scope. There is private memory and team memory, reflected in directories such as .claude/memory/ and .claude/memory-team/ at the conceptual level, with team-aware path logic implemented in files like teamMemPaths.ts. This turns memory into a social system as much as a technical one: some knowledge is personal, some should be shared.
Even more mature is Claude Code’s staleness logic. memoryAge.ts computes human-readable memory age like “today,” “yesterday,” or “47 days ago,” and emits freshness warnings for older memories. This is a subtle but deeply important safeguard. Persistent memory can become false over time. Claude Code acknowledges that memory is a snapshot, not a source of truth.
OpenCode: instruction memory rather than typed memory
OpenCode approaches persistence from another angle. In session/instruction.ts, it discovers AGENTS.md, CLAUDE.md, and legacy CONTEXT.md, both globally and by traversing upward through project directories. It also supports config-driven instruction paths and URL-based instruction sources.
This is less a “memory database” and more an instruction-loading framework. The persistent layer is document-centric. OpenCode assumes that long-lived knowledge is best represented as instruction files, not as many small typed records.
That does not make it weaker; it makes it different. OpenCode is optimized for explicit, inspectable context injection. The system walks the directory tree, discovers instruction files, and loads them into the system prompt pipeline. It also resolves directory-level instruction inheritance as the agent reads files deeper in the project.
OpenCode therefore treats memory mainly as curated instruction context. Claude Code treats memory as both instruction context and an evolving semantic store.
OMO: automatic context injection plus working memory
OMO extends the memory idea in a highly operational way.
First, its context-injector feature automatically injects important project documents, especially AGENTS.md and README.md, into the active prompt flow. This means the agent does not have to remember to read them manually every time. OMO turns project context into an always-on substrate.
Second, the rules-injector hook adds .sisyphus/rules/*.md content when relevant files are touched. This is a form of targeted memory activation. Instead of loading every possible rule up front, OMO can inject rule fragments in response to actual work. In computer systems language, this is closer to demand paging than static initialization.
Third, OMO emphasizes directory-level instruction locality. The codebase and related docs explicitly support hierarchical AGENTS.md placement. The deeper the agent goes into the tree, the more local instruction files can become active. This is important because large repositories often have subdomains with different norms.
Fourth, OMO introduces the Atlas notepad system under .sisyphus/notepads/. These notepads store learnings, issues, decisions, and unresolved problems. This is not exactly the same as Claude Code’s typed long-term memory. It is closer to structured working memory across a larger plan or orchestration run. In classical CS terms, it resembles an external scratchpad: durable enough to survive turns, but still tightly tied to a specific effort.
The distinction matters. Long-term memory stores durable truths about the user or project. A notepad stores intermediate operational knowledge accumulated during coordinated work.
From prompt engineering to context engineering
The deeper shift across all three systems is conceptual. Early AI tooling focused on prompt engineering: write a clever instruction once and hope it generalizes. These systems instead practice context engineering.
Context engineering means designing what information is available, when it becomes available, how it is scoped, and how it ages.
Claude Code expresses this through typed memories, freshness checks, and scope-aware storage. OpenCode expresses it through file discovery, frontmatter-aware instruction parsing, and prompt assembly rules. OMO expresses it through automatic injection, event-triggered rule loading, directory-level knowledge, and orchestration notepads.
This is a major architectural evolution. A prompt is a string. A context system is an information architecture.
Design implications
The best memory systems for coding agents have at least four properties.
First, they distinguish derivable facts from non-derivable facts. If the agent can re-read it cheaply from the repo, it usually should not be stored as memory.
Second, they acknowledge staleness. Memory without aging becomes accumulated hallucination.
Third, they support multiple scopes: personal, team, project, and task-local. These correspond to different ownership boundaries.
Fourth, they make persistence inspectable. Markdown files, notepads, and typed memory documents all share one virtue: humans can audit them.
That is why the future of coding agents is not simply “larger context windows.” Bigger windows help, but they do not solve organization. The real challenge is deciding what belongs in durable instructions, what belongs in long-term memory, what belongs in a temporary working scratchpad, and what should be recomputed from live state.
That is the true shift from prompt engineering to context engineering: not writing better words, but designing better memory boundaries.