DEV Community: Antonio Zhu

OpenCode Needs Memory, Not Another Background Pipeline

Antonio Zhu — Thu, 27 Aug 2026 09:14:39 +0000

I kept explaining the same project facts to new OpenCode sessions.

Not the durable rules that already belonged in AGENTS.md. Those were present. The repetition was smaller and more frustrating: a project-specific convention discovered while fixing a bug, a user preference expressed during a review, or a workflow detail that was useful but too narrow to turn into permanent team policy.

OpenCode already preserves sessions, loads explicit instructions, and compacts long conversations. Those are valuable systems, but none answers a simple cross-session question: after an agent learns something reusable in this project, how does the next session know it?

I built opencode-plugin-memory as a deliberately small answer. It gives the active OpenCode agent four memory tools, stores knowledge as project-local Markdown, and automatically injects a compact index into future system prompts.

The point is not to make every conversation permanent. The point is to stop rediscovering the lessons that should survive.

The gap between instructions and history

There are two tempting but incomplete answers to persistent agent knowledge.

The first is AGENTS.md. It is the right place for rules that must govern behavior: required verification commands, architectural boundaries, security constraints, and repository conventions. It is explicit, reviewable, and authoritative. A model should not have to infer a release requirement from a previous chat.

The second is session history. It records what happened, but a new session does not automatically search old conversations for a relevant decision. Even if it did, raw history is a poor instruction source. It contains tentative ideas, failed attempts, stale facts, and untrusted tool output alongside useful conclusions.

The missing layer is selective recall:

AGENTS.md       -> mandatory, authored instructions
session history -> evidence about one conversation
project memory  -> selected lessons useful in later sessions

That distinction came out of my earlier source-level analyses of what OpenCode actually remembers and how Codex runs its local-memory pipeline. OpenCode core intentionally stops short of a general long-term memory service. Codex takes the opposite route: a background, two-model pipeline extracts and consolidates eligible prior rollouts.

Both choices make sense. But for a single developer working inside one repository, I wanted a third option: no cloud service, no vector database, no delayed consolidation worker, and no opaque state outside the project.

A memory layer the active agent owns

opencode-plugin-memory follows a hot-path design. The active agent decides whether a lesson is worth retaining while it has the task context that makes the judgment meaningful.

It registers four tools:

memory_add saves a reusable project fact or convention.
memory_update corrects or expands an existing memory.
memory_delete archives an obsolete entry instead of erasing it.
memory_read retrieves full entries, optionally filtered by keyword.

The tool descriptions give the agent a narrow policy. It should save an explicit "remember this" request, a recurring bug lesson, a project convention, or a correction that future sessions should respect. It should not save the file it happens to be editing, generic programming advice, or information already documented in AGENTS.md.

That policy matters more than a large store. A memory system that records every task turns future prompts into an untrusted, noisy transcript. This plugin asks for small, deliberate promotion decisions at the moment the evidence is fresh.

The store is ordinary Markdown under the project directory:

.opencode/memory/
  MEMORY.md
  memory_summary.md
  plugin.log

MEMORY.md is the source of truth. You can open it in an editor, review what the agent has learned, correct an entry directly, or restore an archived item. The generated memory_summary.md is only an index. It lists active memory IDs, titles, and tags within a configurable character budget.

On every OpenCode system-prompt transform, the plugin appends that summary to the prompt. The agent has ambient awareness that the project has relevant memory without paying to load the entire handbook on every turn. When a title looks relevant, it calls memory_read for the details.

That is progressive disclosure with plain files:

bounded summary in every prompt
        -> agent recognizes a relevant topic
        -> memory_read loads the full entry

It is simpler than semantic retrieval and, for a compact project knowledge base, easier to inspect when the agent makes a bad decision.

Why Markdown is a feature

Agent memory is often described as a retrieval problem. That framing tends to lead straight to embeddings, vector stores, hidden profiles, and ranking systems. Those tools can be appropriate when an application must search a large, multi-user corpus.

They are not automatically appropriate for a coding project.

For project memory, the harder questions are authority and lifecycle:

Is this a hard rule, a reusable lesson, or a temporary hypothesis?
Can a developer see exactly what will influence a future agent?
What happens when an API, preference, or workflow becomes obsolete?
Can a mistaken memory be corrected without administering another service?

Markdown gives direct answers. The user owns the file. The agent's operations are visible. IDs are sequential, so references remain stable. Deletes are soft deletes: the entry moves to an Archived section, preserving a review path rather than pretending old knowledge never existed.

The plugin also maintains an optional append-only plugin.log for add, update, delete, and error events. This is not a cryptographic audit trail, and it is not meant to be one. It is a practical way to see when the memory layer changed.

Transparency is not only a usability choice. A memory entry becomes part of an agent's future decision context. A local, human-readable store makes that influence inspectable before it becomes mysterious.

Install it in one configuration block

The plugin is available at github.com/chncaesar/opencode-plugin-memory. Add a local clone or package reference to OpenCode's plugin configuration:

// opencode.json or ~/.config/opencode/opencode.jsonc
{
  "plugin": [
    ["/path/to/opencode-plugin-memory", { "maxSummaryChars": 3000 }]
  ]
}

The default summary budget is 2,000 characters, roughly 500 tokens. Raise it when a project has more distinct memory topics; keep it small when prompt cost matters more than ambient recall. Set enableLog to false if the operation log is not useful for your workflow.

The memory directory is created on the first write. There is no server to provision, account to create, or migration to run.

After installation, the useful interaction is intentionally ordinary. Tell the agent to remember a durable lesson when it appears. For example: after finding that a repository requires a specific local verification sequence, the agent can save the reusable workflow detail. In a later session, the summary exposes the title, and the agent can read the full entry before proposing a change.

The result is not an agent that claims perfect recall. It is an agent with a visible project notebook that it can maintain itself.

What this plugin does not try to solve

Small scope is part of the design.

It does not replace AGENTS.md. Mandatory project rules should remain in explicit instructions, where they are always loaded and reviewed as policy. Memory is for selected recall, not the only copy of a requirement that must be followed.

It does not mine every past session in the background. Codex's extraction and consolidation pipeline addresses a different problem: automatically turning a large body of historical work into a curated memory workspace. This plugin puts the decision in the active agent's tool call instead, avoiding a second model, delayed processing, and another trust boundary.

It does not use a vector database. Search is keyword-based and the summary index provides ambient routing. That is a conscious trade-off for modest, project-scoped collections where inspectability is more valuable than fuzzy recall.

It does not add concurrent-write locking. The intended model is normal single-user project work; concurrent OpenCode sessions writing the same MEMORY.md need stronger coordination and tests before that complexity is justified.

Those limitations are not hidden caveats. They define the product. If you need a background policy, evidence retention, semantic search across thousands of conversations, or multi-user conflict resolution, use a system designed for that scale. If you want a local memory layer that remains understandable in a text editor, this is the narrower tool.

The useful middle ground

The choice is not between manual instructions and an elaborate autonomous memory platform.

For many OpenCode projects, there is a useful middle ground: keep rules in AGENTS.md; keep conversations in their session records; let the active agent promote only the reusable lessons into a small, visible, project-scoped memory file.

opencode-plugin-memory implements that middle ground. It makes continuity across sessions a deliberate, inspectable capability instead of a hope that the next agent will rediscover the same context.

For adjacent tools that keep an OpenCode workflow reliable, including readiness checks, database maintenance, session reflection, and multi-machine coordination, see the OpenCode Reliability Toolkit.

Codex Memory Internals: What It Remembers, Who Decides, and How It Compares to OpenCode

Antonio Zhu — Wed, 26 Aug 2026 06:38:08 +0000

I began this investigation with a specific question: can Codex autonomously add, modify, and delete its own memories? The product documentation already says that it has memory. What I wanted to know was who actually decides what survives.

When an old chat contains a useful build command, does deterministic application code copy it into a database? Does the active coding model call a memory tool? Does another model summarize the chat later? When the command becomes obsolete, is the old fact overwritten, invalidated, aged out, or simply left where future agents may still find it?

Those questions led to a more interesting result than a feature checklist. Codex has a genuine cross-session memory subsystem, but its behavior is split between model judgment and deterministic lifecycle code. Models decide what a rollout means and how durable guidance should be rewritten. Runtime code decides which rollouts are eligible, which evidence remains in the working set, when old records are deleted, and when the consolidation model is allowed to run.

That makes the short answer precise:

With local memories enabled, Codex can autonomously add, modify, merge, and remove persistent memory without a user approving each write. User-requested corrections follow a separate append-only note path, while retention, thread deletion, and reset provide additional forms of forgetting.

The rest of this article explains why each word in that answer matters.

This analysis is pinned to OpenAI Codex commit 8444cf63b50a8a88521e0d2970d49f659b48eac7, checked on August 25, 2026. The feature is marked stable in that source tree but remains off by default, so this describes implemented behavior, not behavior every Codex user is currently receiving.

Key Takeaways

Codex local memory is a background two-model pipeline. One model extracts reusable material from each eligible rollout. A second model consolidates those outputs into a global file-based memory workspace.
The LLM owns semantic CRUD, but not lifecycle scheduling. Prompts ask the models to decide what is useful, merge new evidence, rewrite stale guidance, preserve uncertainty, and remove claims whose evidence disappeared. Rust and SQLite code choose candidates, enforce leases, rank inputs, prune old rows, and synchronize files.
Forgetting has several independent mechanisms, not one delete operation. Codex can delete an old extraction after a later no-op, drop rollout summaries that leave the selected set, ask the consolidation agent to remove unsupported guidance, prune unused database rows, remove expired extension resources, forget memory attached to a deleted thread, or reset the entire memory store.
Retrieval is progressive disclosure, not vector RAG. A bounded memory_summary.md is injected into developer instructions. The model then searches MEMORY.md and opens one or two supporting summaries or skills when needed.
Usage feeds retention. Memory citations contain rollout IDs. When Codex emits a citation, runtime code increments usage counts and timestamps for the corresponding Phase 1 records. Later consolidation prefers frequently and recently used evidence.
User corrections are indirect and permission-dependent. After a direct request, Codex can create an append-only ad-hoc note when dedicated memory tools are enabled or the active permission profile separately permits the write. The next consolidation pass interprets that note and updates the generated memory artifacts.
AGENTS.md, session persistence, compaction, and long-term memory remain different systems. Team rules belong in explicit instructions. Rollouts record what happened. Compaction keeps one conversation within its context budget. The memory pipeline promotes selected lessons across conversations.

The Pipeline I Found

Before the pipeline, a definition. A rollout is Codex's term for the complete recorded history of one session: user messages, model responses, tool calls and outputs, turn boundaries, and session metadata, all persisted as a single file under the session directory. It is the raw transcript of one conversation, and it is the input the memory pipeline mines for reusable lessons.

The implementation lives across four layers:

eligible prior rollouts
        |
        v
Phase 1 extraction model
        |
        v
SQLite stage1_outputs
        |
        v
selected evidence + git workspace diff
        |
        v
Phase 2 consolidation agent
        |
        v
memory_summary.md -> MEMORY.md -> summaries / skills / source rollouts

The trigger is more precise than "when a session starts." Memory work is dispatched only after a fresh turn that carries user input has successfully started and the primary environment is configured. The "worker" here is the background task Codex spawns to run that memory pipeline — an asynchronous routine, not a separate process or an independent agent. It returns without doing anything if the session is ephemeral, the memories feature is disabled, the session is a sub-agent rather than a root agent, or the state database is missing.

Once dispatched, the worker runs in the background. It first deletes old, unused extraction rows, then checks the remaining Codex rate-limit percentage; if quota is low, it skips the model work rather than spend tokens near a limit.

The defaults reveal the intended operating model. The MemoryTool feature is stable but off by default, and enabling it turns on both generating and using memories. Extraction only looks back at the previous ten days of rollouts and skips anything that has been idle for fewer than six hours. Consolidation keeps at most 256 raw inputs at a time, and any memory that goes thirty days without use reaches the retention boundary and becomes eligible for pruning.

Those numbers are cost and growth controls, not judgments about meaning. They decide which experiences are worth processing and how much state to keep; the models still decide what the surviving content actually means.

Phase 1: A Model Decides What A Rollout Taught

Phase 1 scans recent interactive root threads whose per-thread memory mode is enabled. It excludes the current thread and rollouts that are too fresh, too old, already current, being processed elsewhere, or outside the bounded startup claim.

For every claimed rollout, Codex loads the recorded items, filters them to memory-relevant model input, and sends the result to a dedicated extraction model with a strict JSON schema. The sanitizer drops developer messages, marked AGENTS.md and skill injections, and compaction records before the rollout reaches the extractor. The model must return:

raw_memory
rollout_summary
an optional rollout_slug

The prompt is unusually explicit about epistemic discipline. User messages are the strongest source for preferences. Tool outputs and verification evidence are the strongest source for repository facts. Assistant proposals should not silently become durable truth. Secrets must be redacted, temporary metrics should be skipped, and a no-op is preferred when a future agent would not plausibly act better because of the memory.

This is autonomous creation, but it is selective creation. A successful extraction upserts one stage1_outputs row per thread. If the source rollout later changes, a newer extraction replaces the old row. If the new model pass returns an empty result, Codex deletes any previous extraction for that thread and schedules consolidation so the higher-level files can forget what no longer has support.

That last case is easy to miss. "No useful memory" is not only an absence of creation. On a regenerated rollout, it can become a deletion signal.

Phase 2: A Model Rewrites The Global Memory

Phase 2 is not a simple concatenation job. It first takes a global lease — a timed lock with an ownership token and periodic heartbeats — so that only one consolidation task can touch the shared memory files at a time, and a crashed worker eventually releases the lock by letting its lease expire. Only then does it select a bounded set of Phase 1 records and materialize them under ~/.codex/memories/.

The selection algorithm prefers usage_count, then recent last_usage, then source recency. Never-used records use their source update time as the fallback. Records outside the unused-memory window are ineligible.

Runtime code rebuilds raw_memories.md, writes one Markdown file per selected rollout under rollout_summaries/, and removes old summary files that are no longer selected. The memory directory is managed as a small Git baseline repository. Codex computes a bounded diff from the previous successful consolidation and writes it to phase2_workspace_diff.md.

If nothing changed and the required output files are valid, Phase 2 exits without calling a model. If inputs were added, modified, or deleted, it starts an internal consolidation agent with:

approval policy set to Never;
collaboration, apps, plugins, MCP servers, and memory recursion disabled;
memory-root-only write access and no network when the parent uses a Codex-managed permission profile;
the parent's enforcement choice preserved when Codex sandboxing is explicitly disabled or delegated to an external sandbox;
a medium-reasoning consolidation model.

The consolidation prompt gives that agent semantic ownership of three outputs:

MEMORY.md, the retrieval-oriented handbook;
memory_summary.md, the compact index injected into future prompts;
optional reusable packages under skills/.

MEMORY.md has a deliberate structure that makes the read path work. Its top-level unit is a # Task Group block, one per task family, headed by a scope: line and an applies_to: line that preserves the working-directory boundary so similar tasks in different checkouts are not confused. Inside each block, ## Task <n> sections come first, each carrying ### rollout_summary_files (with cwd, rollout_path, updated_at, and thread_id) and ### keywords for grep-style retrieval. After the task list come three consolidated sections: ## User preferences, ## Reusable knowledge, and ## Failures and how to do differently, each bullet traceable back to task references like [Task 1].

This shape is why retrieval can be lexical instead of vector-based: the routing handles live in stable headings and keywords, and the durable guidance lives just below them. memory_summary.md then sits above MEMORY.md as a denser, token-budgeted index rather than a second handbook.

The agent is instructed to incrementally merge new evidence, update contradictory guidance, preserve uncertainty when validation is unclear, and minimize churn when existing material is still correct. It must retain task-level provenance through rollout-summary paths, thread IDs, working directories, and update timestamps.

Most importantly, the prompt defines forgetting. Deleted rollout summaries and extension resources form a stale-cleanup queue. The agent searches for memory supported by those inputs, removes only unsupported guidance, preserves facts that still have other evidence, and then cleans the corresponding entries from the summary index.

The runtime verifies that MEMORY.md exists and that memory_summary.md starts with the expected schema marker. It removes symlinks from the workspace. Only after a valid completion does it reset the Git baseline and mark the exact Phase 1 snapshots as consumed.

The semantic result is model-authored. The scheduling, isolation, evidence diff, and acceptance checks are deterministic.

What Add, Update, Delete, And Forget Mean

The word "delete" hides several different contracts in this system.

Operation	Who decides	What actually happens
Add a rollout memory	Phase 1 extraction model	A new DB-backed raw memory and rollout summary are created after the idle rollout passes the signal gate.
Update a rollout memory	Phase 1 extraction model + DB watermark	A changed thread is re-extracted and its newer result replaces the previous row.
Add or merge durable guidance	Phase 2 consolidation model	`MEMORY.md`, `memory_summary.md`, and possibly `skills/` are created or rewritten from selected evidence.
Remove unsupported guidance	Phase 2 consolidation model	Deleted inputs in the Git diff cause evidence-scoped cleanup of consolidated files.
Drop an input from the active set	Deterministic selection	Low-use, stale, or displaced Phase 1 records stop appearing in `raw_memories.md`; their rollout summary files are removed.
Delete stale DB evidence	Deterministic retention	Unselected Phase 1 rows older than the unused-memory cutoff are deleted in bounded batches.
Delete expired extension evidence	Deterministic retention	Timestamped extension resources older than seven days are removed before consolidation.
Forget a deleted thread	Thread lifecycle code	The thread's Phase 1 row and job are deleted; consolidation is enqueued if that evidence was selected.
Apply a user correction	User request -> append-only note -> Phase 2 model	With dedicated tools or separate write permission, the active agent records a small note asking to add, update, or delete information; consolidation applies it to generated outputs.
Forget everything	User control	`memory/reset` or the debug clear command removes memory DB rows and the contents of memory directories while preserving chat threads and their memory-mode settings.

This is stronger than "the model can edit a Markdown file." It is a lifecycle with several independent forgetting paths.

It is also weaker than a transactional fact database. The consolidated handbook does not assign every claim a stable fact ID, confidence score, validity interval, or tombstone. The consolidation prompt asks the model to preserve provenance and uncertainty, but those properties live in Markdown structure and model compliance rather than a schema-enforced knowledge layer.

User Authority Is Present, But Indirect

The read-path prompt is the instruction block Codex injects into every session to tell the active model how to use memory: when to consult it, how to search it, and how to cite it. Its rules include a boundary on writing. It tells the active model that it may update memory only after an explicit direct request from the user. Even then, it should not directly edit MEMORY.md or memory_summary.md. When the dedicated memory tools are enabled, or the active permission profile separately permits the write, it can create one timestamped Markdown note under:

~/.codex/memories/extensions/ad_hoc/notes/

The dedicated add_ad_hoc_note tool enforces create-new semantics, a timestamped filename, a small path scope, and no overwrite. The extension instructions tell consolidation that every note is authoritative for memory content, including requests to add, edit, or delete remembered information. They also say never to delete the note itself and to treat its content as data rather than executable instructions.

This creates a useful separation:

user intent: append-only evidence
generated state: rewritable memory artifacts

The note is an inspectable, append-only correction artifact, but it is not a source-authenticated audit log: it contains the model's transcription rather than the original user message, identity, or source hash. The consolidation model decides how to reflect it in the generated memory hierarchy, and users must compare it with the originating conversation when exact attribution matters.

There are still important limits. Dedicated memory tools are disabled by default even after the main feature is enabled, and the memory root is otherwise read-only to a normally managed workspace-write agent. The background consolidation agent runs with no per-write approval. Users can inspect the plain files, toggle whether a chat can use or contribute memory, disable the feature, or reset the store, but there is no mandatory review queue for every inferred preference.

For stable team rules, the official documentation therefore gives the right advice: keep them in AGENTS.md or checked-in documentation. Memory is a recall layer, not the only copy of a requirement that must always govern behavior.

The Read Path Closes The Loop

Codex does not embed every memory and retrieve nearest neighbors. It uses a staged file hierarchy.

At thread start, the memory extension reads memory_summary.md, truncates it to a fixed token budget, and injects it into developer instructions. That prompt tells the model to skip memory only for clearly self-contained tasks. For a relevant or ambiguous task, it should extract keywords from the summary, search MEMORY.md, and open only one or two directly referenced skills or rollout summaries.

This design makes retrieval partly deterministic and partly agentic:

the summary is automatically visible;
the model decides whether deeper memory is relevant;
file search provides lexical retrieval;
the model decides which evidence to open;
citations expose which memory influenced the answer.

The citation path does more than improve observability. A citation has two parts. The file entries (MEMORY.md:234-236, rollout_summaries/...:10-12, skills/...) point at the Markdown artifacts Phase 2 produced. The rollout IDs point back at the Phase 1 database records those artifacts were consolidated from. Codex parses those IDs from the final model output, increments usage_count, and sets last_usage for the corresponding Phase 1 records. Future Phase 2 selection then favors evidence that has actually helped later turns.

That is a lightweight feedback loop:

memory is selected -> model uses and cites it -> runtime records usage
-> frequently useful evidence remains eligible -> consolidation sees it again

It is not reinforcement learning. No model weights are updated. It is runtime ranking and retention driven by model-produced citations.

What Codex Memory Is Not

Several adjacent mechanisms can look like the same feature from the outside.

AGENTS.md is deterministic instruction context. It is authored explicitly and should contain rules that must reliably apply. Codex memory is generated recall that may be incomplete, stale, or absent when the feature is disabled.

Rollout storage is durable evidence. It lets Codex reopen or analyze what happened in one thread. A rollout becomes cross-session memory only after Phase 1 extracts it and Phase 2 selects and consolidates it.

Compaction is short-term context management. It summarizes or replaces old model-visible history so one active thread can continue within a context limit. It does not decide that a lesson should influence unrelated future threads.

These distinctions match the framework I used in OpenCode Memory Internals:

instructions: what should govern behavior
history: what happened
working context: what the model can see now
long-term memory: what selected lessons should influence later sessions

Codex implements all four. OpenCode core currently implements the first three.

Codex Versus OpenCode

The architectural difference is not that one tool writes files and the other does not. Both can write files. The difference is ownership.

OpenCode loads AGENTS.md, configured instruction sources, and durable session history. It compacts long sessions. Its /init command can ask an active agent to create or improve project instructions. But core does not run a background policy that mines old sessions, promotes lessons, reconciles them with a global memory, and retrieves that memory in new sessions.

Codex does. Its runtime owns eligibility, extraction jobs, a separate memories database, consolidation scheduling, usage accounting, retention, prompt injection, citations, and reset. Models supply the semantic judgments inside that lifecycle.

Dimension	Codex local memory	OpenCode core
Write trigger	Background processing of eligible idle rollouts	Explicit user or agent file edit
Semantic writer	Phase 1 and Phase 2 models	No dedicated memory writer
Automatic update	Re-extraction plus incremental consolidation	No general cross-session update path
Automatic forgetting	Selection, retention, input deletion, and model cleanup	No general cross-session forgetting policy
Store	SQLite evidence plus generated files under Codex home	Instruction files plus session-scoped SQLite history
Retrieval	Injected summary, lexical search, progressive file reads	Deterministic instruction injection; no core cross-session semantic recall
Feedback	Citations update usage and retention rank	No equivalent core memory-usage loop
User controls	Per-chat use/contribute settings, config, inspection, reset	Explicit instruction editing and session controls

OpenCode's simpler boundary is easier to audit. Codex's pipeline can reduce repeated steering. The price is a larger trust surface: old conversation content is transformed into future developer context by models running in the background.

Where Other Memory Systems Put The Decision

Comparing systems by storage technology alone is misleading. The more useful question is where memory policy lives.

System	Who decides memory operations?	Update and forgetting model	Retrieval model	Primary design center
Codex	Background extraction and consolidation models inside a runtime-managed pipeline	LLM rewrites plus deterministic retention and reset	Prompt-loaded summary, lexical search, progressive disclosure	Local coding-agent recall from prior work
OpenCode core	User or active agent through ordinary instruction files	Explicit file maintenance	Deterministic instruction loading	Transparent instructions and durable sessions
Claude Code auto memory	Active Claude model during the session	Model edits or deletes local Markdown; user can edit or delete it	Bounded `MEMORY.md` index plus on-demand topic reads	Immediate per-repository learning from corrections
Letta Agent SDK	The active agent edits git-backed MemFS; optional Dreaming launches background subagents	Committed file revisions plus background consolidation when configured	`system/` files stay in context; other files appear as a tree and are read on demand	Versioned, agent-owned memory that follows the agent
Mem0	An extraction pipeline compares new messages with retrieved candidates	LLM chooses `ADD`, `UPDATE`, `DELETE`, or no change	Vector search within entity scope, with entity-aware ranking	Application memory as a service or library
LangMem	Developer-configured hot-path tools or background managers	LLM transforms profiles or collections; store layer upserts/deletes	Direct lookup, semantic search, and metadata filters	Composable memory primitives for LangGraph applications
Graphiti / Zep	Ingestion pipeline extracts entities, facts, and temporal relationships	Superseded facts are invalidated with history preserved	Hybrid semantic, keyword, and graph traversal	Time-aware facts, relationships, and provenance
AgeMem	The task model itself selects memory actions as part of its learned policy	Explicit Add, Update, Delete, Summary, and Filter actions	Learned Retrieve action	Joint long-term and short-term memory control through RL

Three patterns stand out.

Agent-Directed Memory

MemGPT framed memory as an operating-system problem: move information between a small fast context and larger external storage. Letta's legacy V1 SDK expressed that lineage through editable memory blocks and archival tools. The current Letta Agent SDK instead uses git-backed MemFS: files under system/ remain in context, other files are exposed as an on-demand tree, and optional Dreaming subagents consolidate recent conversations in the background.

The active agent can still edit its own persistent memory, while Dreaming moves some consolidation off the hot path. That combination illustrates that agent-directed and background memory do not have to be mutually exclusive.

Claude Code's auto memory is also close to the hot path. Claude writes a compact MEMORY.md index and topic files during the session. It can learn immediately from a correction, and users can inspect, edit, or delete the files. There is no separate delayed consolidation architecture comparable to Codex's two-phase pipeline.

Background Memory Pipelines

Mem0 and LangMem make the extraction pipeline an application primitive. New messages are compared with existing state, and an LLM chooses whether to insert, update, delete, or consolidate memories. LangMem explicitly supports both hot-path and background formation and distinguishes profiles, collections, episodes, and procedural prompt updates.

Codex belongs in this family, but with a coding-agent-specific choice: it stores rich per-rollout evidence, consolidates into a human-readable handbook, and lets future models progressively disclose detail through file search rather than requiring a vector store.

Temporal And Learned Policies

Graphiti treats contradiction as a temporal data problem. Facts have validity windows, raw episodes preserve provenance, and superseded relationships are invalidated rather than erased. This is stronger than asking a Markdown-writing model to decide which sentence sounds current, especially when historical truth matters.

AgeMem moves the decision one level deeper. Add, Update, Delete, Retrieve, Summary, and Filter are actions in the model's policy. A three-stage reinforcement-learning curriculum connects early storage decisions, short-term context control, and eventual task reward.

Codex does not do this. Its models are guided by detailed prompts inside a fixed pipeline. Usage changes selection, but task outcomes do not train a memory policy. The distinction is between a model making memory judgments and a model trained to make memory judgments.

The Trust Boundary Is The Real Architecture

The most consequential Codex design choice is not Markdown versus vectors. It is the point where untrusted history can become future developer context.

"Local" describes the store, not necessarily the processing boundary. Eligible chat content and path metadata are submitted to the configured model provider for extraction, and generated memory later returns in model requests. Secret redaction covers the serialized rollout input and generated fields, but it does not remove every piece of personal, proprietary, or path-identifying information.

The implementation adds several defenses:

Phase 1 tells the model to treat rollout text and tool output as data, not instructions.
Generated fields pass through secret redaction before entering the memories database.
An optional disable_on_external_context setting marks threads that used web search, MCP, tool search, or similar external context as polluted and excludes them from generation.
For Codex-managed permission profiles, Phase 2 has no network and writes only inside the memory root; explicitly disabled or externally enforced parent profiles are preserved instead.
Consolidation threads are ephemeral and cannot recursively generate memories.
Required artifacts and symlink safety are checked before a run is accepted.
Retrieval requires citations, and unverified memory-derived facts should be described as potentially stale.

The optional pollution guard deserves attention because it is off by default. When enabled, external context changes a thread's memory mode to polluted. If the thread had already contributed selected evidence, Codex schedules consolidation so that evidence can be removed from the active memory set.

This is an explicit answer to a prompt-injection question: should web pages and third-party tool output be allowed to influence cross-session memory? Codex lets the user choose a conservative answer, but does not make it the default.

The remaining risks are structural. Secret redaction is not a proof that every sensitive fact is gone. Markdown provenance is not a cryptographic chain of custody. A no-approval consolidation agent can still infer an unstable preference or overgeneralize a one-off correction. Citation-based usage can reinforce a memory because models keep citing it, not necessarily because it is correct.

Memory quality therefore cannot be reduced to recall rate. It needs authority, provenance, correction, and deletion semantics.

What Runtime Builders Should Copy

The first lesson is to split semantic policy from lifecycle policy. Let models judge meaning, but let deterministic code bound when they run, what evidence they receive, where they can write, and how failures are retried.

The second lesson is to make deletion evidence-driven. Codex does not merely tell a model to "keep memory fresh." It presents a Git diff that includes removed inputs and asks the model to delete only claims whose support disappeared. That is still probabilistic, but it gives forgetting a concrete cause.

The third lesson is to keep the read path bounded. Always loading a small routing index and progressively opening detail is easier to inspect and budget than injecting an unbounded profile or retrieving a large opaque set of nearest neighbors.

The fourth lesson is to feed usage back into retention without confusing usage with truth. Citations provide a practical relevance signal. They should not become the only quality signal, because repeated retrieval can create a self-reinforcing mistake.

The fifth lesson is to keep hard rules outside learned memory. A test command that must run before release belongs in AGENTS.md. A preference inferred from several prior interactions may belong in generated memory. The system should not require a probabilistic promotion pipeline to rediscover mandatory policy.

Source Map

The Codex claims above come primarily from these files in the pinned source tree:

codex-rs/features/src/lib.rs
codex-rs/config/src/types.rs
codex-rs/app-server/src/request_processors/turn_processor.rs
codex-rs/memories/write/src/start.rs
codex-rs/memories/write/src/phase1.rs
codex-rs/memories/write/src/phase2.rs
codex-rs/memories/write/src/storage.rs
codex-rs/memories/write/src/workspace.rs
codex-rs/memories/write/templates/memories/stage_one_system.md
codex-rs/memories/write/templates/memories/consolidation.md
codex-rs/ext/memories/templates/memories/read_path.md
codex-rs/state/src/runtime/memories.rs
codex-rs/ext/memories/src/extension.rs
codex-rs/ext/memories/src/local/ad_hoc_note.rs

The product-level behavior and controls are documented in Codex Memories. The comparison uses the primary project documentation and papers linked in the relevant sections above.

I expected to find either a simple memory tool or a conventional extract-and-vector-search pipeline. Codex implements something more opinionated: a delayed two-stage editorial process over local evidence, with a Git diff acting as the bridge between deterministic retention and model-driven rewriting.

That architecture answers the original question. The LLM does decide what Codex remembers, but it does not decide alone. Runtime code determines which experiences are eligible to become evidence, which evidence remains economically viable, and when the model must reconcile deletion. Reliable memory comes from that division of authority, not from granting a model unrestricted access to a persistent file.

OpenCode Memory Internals

Antonio Zhu — Tue, 25 Aug 2026 06:23:29 +0000

I started this investigation after finding 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. The operational question was simple: had OpenCode decided to preserve those facts, or had someone explicitly written them?

The session record answered it. An agent had created the files through an ordinary file tool after an explicit user request. A project-local instructions configuration then loaded them on every provider turn. What looked like autonomous memory was user-triggered file authoring plus deterministic prompt injection.

That result sent me looking for the actual memory subsystem. There is no general runtime-managed service that decides what to save, updates facts when they change, and semantically retrieves useful knowledge in later sessions.

What users experience as "memory" is produced by three different mechanisms with different owners and failure modes: instruction files are loaded into the system prompt, durable session events and projected messages are persisted in SQLite, and old model-visible context is replaced by a generated compaction checkpoint when the request grows too large. These mechanisms work together, but they do not form an autonomous long-term memory manager.

That distinction matters. If a coding agent remembers a project rule because AGENTS.md is injected on every turn, that is not learned memory. If it can reopen an old transcript from SQLite, that does not mean a new session can retrieve facts from it. If a long session survives by summarizing its history, that does not mean the runtime selected the most important information.

This 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. Where the two paths differ, I call out the difference rather than treating them as one implementation.

Primary code references:

packages/opencode/src/session/instruction.ts
packages/opencode/src/session/prompt.ts
packages/opencode/src/session/llm/request.ts
packages/opencode/src/session/system.ts
packages/opencode/src/session/prompt/beast.txt
packages/opencode/src/tool/read.ts
packages/opencode/src/session/compaction.ts
packages/opencode/src/session/message-v2.ts
packages/opencode/src/command/index.ts
packages/opencode/src/command/template/initialize.txt
packages/core/src/instruction-context.ts
packages/core/src/session/context-epoch.ts
packages/core/src/session/runner/llm.ts
packages/core/src/session/history.ts
packages/core/src/session/sql.ts
packages/core/src/session/compaction.ts
packages/core/src/database/database.ts

Key Takeaways

OpenCode does not have one memory system. It has an explicit instruction layer, a durable session layer, and a bounded working-context layer. Calling all three "memory" hides the most important operational differences.

Project knowledge is mostly prompt injection. AGENTS.md, CLAUDE.md, and configured instructions are read from files and placed in the system prompt. The loader reads them; it does not maintain them.
Session persistence is not cross-session recall. OpenCode durably stores messages, tool calls, tool results, and durable events in SQLite. Streaming text, reasoning, tool-input, and compaction deltas are transient. The stored data makes sessions reopenable and inspectable, but it remains scoped to the session unless another component explicitly reads it.
Compaction changes what the model sees, not what the database retains. Old history remains durable, while normal model requests continue from a generated checkpoint plus recent context.
OpenCode does not have a general runtime policy that promotes conversation facts into long-term memory. There is no built-in embedding index, vector retrieval path, user-profile store, or fact confidence model. One provider-specific prompt contains a narrow file-memory convention, but core does not manage or retrieve that file as a memory service.
/init is guided instruction authoring, not background learning. It asks the active agent to create or improve AGENTS.md after the user invokes the command.
The legacy and V2 instruction paths are not identical. The desktop-compatible path supports AGENTS.md, optional CLAUDE.md, configured local files, and HTTP instruction sources. The current V2 InstructionContext observes AGENTS.md files only.

A Better Mental Model

The easiest way to reason about OpenCode memory is to ask two questions for every piece of information:

Where is it stored?
Is it included in the next model request?

Those are not the same question.

Layer	Stored in	How it reaches the model	Scope
Ambient instructions	Markdown files or configured URLs	Injected as system context	Project or configured scope, across sessions
Durable session history	SQLite messages, parts, inputs, and durable events	Selected history is converted into model messages	One session
Compaction checkpoint	A durable summary message or compaction event	Replaces older active history in later requests	One long session

The request path is approximately:

agent system prompt
+ ambient instructions
+ selected session history
+ latest user input
+ tool definitions
-> provider request

The database may contain much more than the provider request. A project may also contain instructions that are reloaded independently of the transcript. "The runtime has it" and "the model can currently reason over it" are separate properties.

Layer One: Ambient Instructions

In the desktop-compatible path, instruction discovery lives in packages/opencode/src/session/instruction.ts. It collects several classes of sources.

The global source is an AGENTS.md under the OpenCode config directory, with optional compatibility loading for ~/.claude/CLAUDE.md. At project level, it searches upward for instruction files. AGENTS.md is preferred, followed by CLAUDE.md, then the deprecated CONTEXT.md; the first filename family with matches wins. The project configuration may also add instructions entries that resolve to local paths, glob patterns, or HTTP URLs.

The loader reads those sources and renders each one with its origin:

Instructions from: /path/to/AGENTS.md
<file content>

SessionPrompt calls instruction.system() while preparing each provider step. It combines the resulting text with environment context, MCP instructions, and skills. LLMRequestPrep.prepare(...) then joins that material with the selected agent prompt and any per-user system content before creating provider system messages.

This is simple and strong. A project rule does not depend on the model remembering a conversation from last week. It is supplied again as authoritative context. Editing the file changes the context future turns receive.

It is also important not to overstate what happens. The instruction loader has read, discovery, and fetch behavior. It has no code that decides a new lesson is worth preserving, rewrites a stale rule, or deletes a contradiction. A human or an agent using ordinary file tools must make those edits.

OpenCode adds one useful directory-sensitive behavior. When the read tool opens a source file, the runtime can discover a nearer instruction file between that file and the project root and attach it to the tool result as a system reminder. A monorepo can therefore keep broad rules at the root and narrower rules close to a package. This is deterministic path lookup, not semantic retrieval.

What `/init` Actually Does

The built-in /init command is the closest OpenCode gets to authoring persistent project memory. Its command description is "guided AGENTS.md setup," and its prompt asks the agent to investigate the repository and create or update AGENTS.md.

The prompt is carefully scoped. It tells the agent to inspect manifests, CI, developer commands, existing instructions, and representative architecture files. It asks for high-signal facts that future sessions would otherwise miss, and it explicitly rejects generic advice and unverified claims.

But /init is user-triggered. It does not run at the end of every session or perform a dedicated transcript-mining pass for newly learned facts. It executes within the normal active-session context and uses the normal agent and file-writing tools to maintain one explicit instruction artifact.

That makes /init closer to generating repository documentation than to an always-on memory policy.

A Narrow Provider-Prompt Exception

There is one built-in convention that prevents a completely categorical "no memory" claim. For model API IDs containing gpt-4, o1, or o3, packages/opencode/src/session/system.ts selects prompt/beast.txt. That provider prompt tells the agent that user preferences may be stored in .github/instructions/memory.instruction.md and that, when the user explicitly asks it to remember something, it may create or update that file.

This is a prompt-level file convention, not a runtime memory service. The normal instruction loader does not search for memory.instruction.md. Core does not index the file, reconcile contradictions, attach confidence or provenance, or automatically retrieve it across sessions. The model can use ordinary file tools to write or read it if the prompt and current task lead it there.

The distinction is useful: OpenCode ships a provider-specific instruction that suggests a memory behavior, but not a provider-independent subsystem that owns memory state.

The V2 Instruction Path

The newer core runtime makes ambient context more explicit. packages/core/src/instruction-context.ts registers instructions as a typed SystemContext source. It observes the global config AGENTS.md and project AGENTS.md files between the active directory and project root, then renders them into an instruction baseline.

SessionContextEpoch persists both the rendered baseline and a structured snapshot for the session. Before a provider turn, SessionRunner prepares the current system context and sends the selected agent system prompt plus the baseline to the model. If the observed instruction state changes, the context system can produce an explicit replacement update rather than silently mixing old and new versions.

This is a better model for a durable agent runtime: system context has identity, a baseline, and update semantics.

It is not yet feature-equivalent to the desktop-compatible loader. The current V2 InstructionContext searches for AGENTS.md; it does not wire the optional CLAUDE.md compatibility source or the local and remote paths declared by the legacy instructions configuration. Anyone migrating behavior between the two runtimes should verify the active path instead of assuming that "OpenCode loads instructions" means the same thing everywhere.

Layer Two: Durable Session History

OpenCode's second memory-like mechanism is session persistence.

The SQLite database runs in WAL mode and normally lives under OpenCode's data directory as opencode.db, with channel-specific filenames available for development builds. The schema contains both the desktop-compatible message projection and the newer event-oriented session tables.

The desktop-compatible path stores message rows and separate part rows. A message is not just text. Parts represent text, reasoning, files, tool calls, tool results, step boundaries, snapshots, patches, errors, and compaction markers. The session processor updates these records while the provider stream and tools are running.

The V2 path adds durable session inputs, ordered durable events, projected session_message rows, and a context epoch. Prompt admission and model execution are separated. Durable lifecycle events describe what happened; projectors create query-friendly messages; the runner reloads selected history before the next provider turn. High-frequency text, reasoning, tool-input, and compaction delta events remain transient rather than being inserted into the durable event stream.

This persistence gives OpenCode several properties commonly mistaken for long-term memory:

a session survives process restart;
the UI can reopen old conversations;
tool execution can be inspected after completion;
clients can rebuild projections from durable state;
debugging can refer to stable session, message, part, and tool-call identities.

But persistence alone does not create recall. A new session does not search every old session for facts about the user or repository. There is no built-in retrieval query such as "find prior decisions relevant to this prompt." Unless content has been moved into an instruction file or supplied by a plugin, old session data remains old session data.

This boundary is worth preserving. Durable history is an audit and recovery substrate. Cross-session memory is a selection and trust problem. Combining them implicitly would make every old statement a candidate instruction, including mistakes, obsolete plans, secrets, and prompt-injected content.

Layer Three: Bounded Working Context

Even within one session, the model cannot see an unlimited transcript. Tool outputs, file reads, reasoning, and repeated provider turns eventually exceed the model's context window.

OpenCode handles that with compaction.

The desktop-compatible implementation estimates the active history and retains a recent tail within a configured budget. For the older head sent to the summarizer, it strips media and truncates large tool outputs, then asks a dedicated compaction agent to generate a summary. It persists that summary as an assistant summary message. filterCompacted(...) later reorders model-visible history so the provider sees the compaction request, its summary, the retained tail, and subsequent work instead of the full original transcript.

The same path has a separate optional pruning mechanism. When compaction.prune is enabled, it scans older completed tool outputs while protecting a recent token budget. Outputs selected for pruning remain in SQLite but are marked compacted; later model-message conversion replaces their content with [Old tool result content cleared] and drops their attachments. This frees model context without creating a new summary checkpoint. It is disabled unless configured and should not be confused with history summarization.

The V2 implementation uses a durable checkpoint-and-retry design. When a request estimate crosses the context threshold, or the provider reports overflow before assistant output has started, it serializes older history, keeps recent context, generates a bounded summary, persists a compaction event, and retries from the new checkpoint. Future active-history queries begin at the latest compaction boundary. Older rows remain in SQLite but are no longer part of normal provider requests.

The three layers are deliberately separate:

durable history: retained
active history: shortened
model-visible history: summary checkpoint + recent context

This is continuity under a hard context limit, not intelligent forgetting. The trigger is size, not relevance. The summarizer may preserve objectives, files, errors, and next actions, but there is no policy that scores every message by future utility. A detail omitted from the checkpoint still exists in storage, yet the model will not recover it through the normal continuation path.

I covered the V2 checkpoint algorithm and its limits in more detail in OpenCode V2 Compaction Internals. For the memory model, the central point is simpler: compaction is a lossy projection over durable history.

What OpenCode Does Not Implement

After tracing these paths, several negative claims are as important as the positive ones.

OpenCode does not currently provide a general runtime-managed autonomous memory store with:

embedding generation and vector search over remembered facts;
cross-session retrieval based on semantic similarity;
provider-independent add, update, delete, or forget memory tools;
automatic extraction of user preferences or repository decisions;
confidence, provenance, contradiction, expiration, or access-control metadata for facts;
a background policy that promotes session content into long-term memory;
reinforcement learning that teaches the model when to store or retrieve information.

Provider SDK types may mention embeddings, file search, or vector stores. Plugins may inject external context or replace compaction behavior. Neither means OpenCode core owns a semantic memory subsystem.

The beast.txt convention also does not change this conclusion. It tells a subset of models that they may edit a particular file after an explicit request. It does not provide automatic extraction, loading, semantic retrieval, conflict resolution, or lifecycle management for the resulting content.

A user can build a useful approximation by keeping Markdown outside a public repository and referencing it through project-local instructions. That produces private, cross-session context without modifying upstream files. It is still user-maintained prompt context. OpenCode reads it because the configuration points to it; OpenCode does not decide what belongs there.

Why The Simpler Design Is Defensible

It is tempting to treat the missing autonomous layer as an obvious gap. The trade-off is more complicated.

Instruction files are transparent. They can be reviewed in a normal editor, versioned when appropriate, scoped by directory, and corrected without inspecting an opaque index. They are strong context because they enter the system prompt deliberately.

Session persistence is auditable. It records what happened without silently turning every conversation into future policy. A user can delete, archive, inspect, or export sessions without also reasoning about which facts were extracted into another store.

Summary compaction is bounded and observable. It has real information-loss risk, but it creates an explicit checkpoint instead of silently dropping arbitrary history. Optional tool-output pruning follows a different path: it leaves a durable compacted marker and substitutes a visible placeholder in later model context.

An autonomous memory layer would need answers to harder questions:

Which statements are facts, plans, preferences, or temporary hypotheses?
Who is allowed to write a persistent fact?
How is a contradiction resolved?
When does a repository change make an old architectural fact stale?
Can untrusted file content become cross-session memory?
How can a user inspect why a memory was retrieved?
What does deletion mean when memories have been summarized or duplicated?

For a coding agent, these are safety and provenance questions, not only retrieval-quality questions. A wrong remembered API contract can cause a bad patch. A remembered secret can leak into an unrelated request. A stale build instruction can waste every future session.

OpenCode's current architecture avoids those risks by keeping durable rules explicit and durable transcripts session-scoped. The cost is that users and agents must deliberately promote important knowledge into AGENTS.md or another configured instruction source.

What Agent Runtime Builders Should Copy

The first lesson is to stop using "memory" as one undifferentiated feature name. Define at least three contracts:

instruction context: what should govern behavior
durable history: what happened
working context: what the model can see now

Each contract needs different storage, authority, lifecycle, and failure handling.

The second lesson is that durable storage and model visibility should remain separate. Keeping the full transcript is valuable for audit and recovery. Sending the full transcript forever is impossible. Compaction should create an explicit boundary so the runtime can explain what remains durable and what remains visible.

The third lesson is to treat instruction mutation as a privileged operation. OpenCode's loader is read-only. Even /init requires user action and uses ordinary file tools. If a future memory subsystem writes persistent context automatically, it should preserve source, timestamp, confidence, scope, and a review path rather than quietly editing the agent's future system prompt.

The final lesson is that a simple file can be a good memory primitive when the requirement is stable project guidance. It is inspectable, portable, and deterministic. Vector retrieval and learned memory policies solve different problems. Adding them should start from a concrete failure that files, session history, and compaction cannot solve.

OpenCode remembers less than the word "memory" suggests, but its boundaries are useful. Project instructions say what should remain true. SQLite records what happened. Compaction decides what can still fit. None of them autonomously decides what deserves to become a long-term fact.

That is the core architectural claim: reliable agent memory begins by separating authority, durability, and visibility, not by adding a vector database.

I also maintain an OpenCode Reliability Toolkit for readiness checks, database maintenance, session reflection, and multi-machine coordination.

The Agent Session Is the New Log File

Antonio Zhu — Wed, 19 Aug 2026 02:48:05 +0000

I kept seeing the same failures in different clothes. An agent would finish a task without running the right verification. Another session would drift because my first instruction was too vague. A third would reveal a missing tool primitive only after the agent had faked it badly with shell glue. None of these incidents were mysterious while they were happening. The mystery was why I kept rediscovering them one session at a time.

The evidence was already there. OpenCode had the full conversation: what I asked, what the agent assumed, which tools it called, where it stopped, where I corrected it, and which mistake repeated from last week. But after a task ended, that evidence mostly turned back into scrollback. I might remember the pain, maybe write one rule into AGENTS.md, maybe not. The session itself disappeared from the engineering process.

That started to feel wrong. Code gets reviewed. Logs get searched. CI failures get archived. Production incidents get postmortems. But the conversation that produced the code, the test run, the bad deployment check, or the missing verification step is often treated as disposable. For AI-assisted development, that conversation is not disposable. It is the log of the human-agent system.

The part we do not review

When a pull request goes wrong, I can inspect the diff. When a deployment goes wrong, I can inspect logs and metrics. When a test fails, I can inspect the failing command and output. Those artifacts are boring, durable, and searchable. They give the next debugging pass something firmer than memory.

Agent sessions are different. They are full of useful evidence, but they are rarely treated as an artifact worth reviewing. The usual review stops at the code: did the patch compile, did the test pass, did the diff look reasonable? That misses a layer above the code, where many AI failures actually begin.

The instruction may have been underspecified. The agent may have edited before reading enough context. The task may have needed a global search, but the conversation only named one file. The verification boundary may have been wrong: the agent checked that a command returned success, not that the returned data meant what success was supposed to mean. The tool gap may have been obvious in hindsight because the agent kept recreating the same fragile shell loop, but no one stopped to ask whether that loop should become a real primitive.

These are not code-review findings. They are session-review findings. You only see them by reading the conversation as an execution trace.

A session is telemetry

Once I started thinking of sessions as telemetry, the useful question changed. It was no longer: was this answer good? That question is too local. A single answer can be fine while the workflow around it is broken.

The better question is: what keeps happening?

If I correct the same instruction three times, that is not a prompt problem anymore. It is a missing rule. If an agent repeatedly invents a polling loop with sleep and curl, that is not a one-off bash mistake. It is a missing tool. If every large task ends with me saying, "you should have checked the rest of the codebase too," that is not an unlucky review comment. It is a missing checklist step.

This is the same move engineers already make everywhere else. One failed request is an error. A pattern of failed requests is an SLO problem. One flaky test is annoying. A cluster of flaky tests is a signal about architecture, isolation, or ownership. One bad agent session is just a bad session. A repeated agent-session shape is workflow telemetry.

The hard part is that humans are bad at remembering this evidence. I remember the emotional contour of a session much better than the actual sequence of events. I remember that I got frustrated. I do not reliably remember whether the first mistake was my instruction, the agent's shortcut, a missing tool, or a verification step that looked complete but was aimed at the wrong thing. If I want to improve the workflow instead of just complain about it, I need the transcript.

The plugin

So I wrote opencode-session-reflection, a small OpenCode plugin that adds one tool: session_reflection.

The installation path is intentionally boring:

{ "plugin": ["opencode-session-reflection"] }

Restart OpenCode, then ask it to review recent sessions. The registered session_reflection tool is the primary interface; /session-review is only an optional local-development helper. The plugin reads session metadata and transcripts through OpenCode APIs, with cross-project discovery through /experimental/session; it never accesses SQLite directly.

The analysis prompt focuses on three categories.

First: developer-to-agent communication gaps. Was the task framed poorly? Was the scope ambiguous? Did I fail to say whether I wanted discussion or implementation? Did I omit acceptance criteria or verification requirements that I actually knew at the time?

Second: recurring OpenCode mistakes. Did the agent edit before reading context? Did it claim completion without verification? Did it fix one reported occurrence without searching for the same pattern elsewhere? Did it ignore project rules, overbuild, or stop early?

Third: plugin, skill, command, or rule opportunities. This is the most important category for me. The goal is not to turn every annoyance into automation. The goal is to find repeated friction where OpenCode can observe a reliable trigger and take a safe action. Some failures should become a rule. Some should become a skill. Some should become a slash command. A few deserve a plugin.

The plugin writes selected session ids, hashed directory paths, message counts, transcript counts, tool-call counts, prompt hashes, and saved report paths under the OpenCode config directory. Redacted audit metadata stays local and is not uploaded by the plugin. It does not store raw transcripts or session titles in the audit manifest. Selected session evidence may reach the model provider configured in OpenCode.

Saved Markdown reports are different from the redacted audit manifest: they contain the supplied analysis and may preserve excerpts selected by the model. Saved Markdown reports may contain sensitive excerpts; users control their retention and deletion. Treat both reports and local audit metadata as private.

That boundary matters. A session-review tool should not quietly become a second telemetry product. The point is to help the developer inspect their own local workflow, not to upload their mistakes somewhere else.

Why this belongs in the plugin ecosystem

The obvious use is personal: run it on the last few sessions and see what you keep doing wrong. That is already useful. But the more interesting use is upstream of plugin design.

I recently wrote opencode-waitfor because I kept watching agents fake readiness checks with brittle shell loops. The pattern was concrete. The tool boundary was clear. A URL, port, or command should be polled until a condition holds or a timeout returns the last observed state. That is a good plugin because the repeated behavior was observable and the replacement primitive was smaller than the broken behavior it displaced.

But not every repeated failure is that clean. Some are better handled by an AGENTS.md rule. Some need a skill because the real work is reasoning discipline, not API access. Some only need a slash command that packages a known sequence of prompts and tool calls. Some should not be automated at all because the trigger is too ambiguous or the action is too risky.

That is why I wanted the reflection step to ask about feasibility and value, not just annoyance. Can OpenCode detect the situation without brittle transcript parsing? Is the required data available through the SDK? What are the false positives? Does an existing plugin or command already cover most of the need? Would this help other OpenCode users, or is it just a fossil from my private workflow?

Good agent tooling should come from repeated evidence, not imagination. Otherwise it is too easy to build impressive little tools for problems that occurred once, or tools that automate the part that should have stayed under human approval. A session review is a filter. It turns "that was annoying" into "this happened four times, the trigger is visible, the safe action is narrow, and the value is real."

Start with one repeated failure

If you use OpenCode, the useful experiment is small. Install the plugin, run a review over your last few sessions, and look for one repeated failure. Not ten. One.

Maybe it is a communication habit: you keep sending underspecified requests and then correcting the agent two rounds later. Maybe it is a verification habit: the agent keeps checking that commands ran, not that the right thing changed. Maybe it is a tool gap: the agent keeps synthesizing the same fragile shell pattern because no better primitive exists. Pick the clearest one and decide what kind of artifact it deserves.

If it applies across future sessions, write a rule. If it is a reasoning workflow, write a skill. If it is a repeated user-invoked flow, write a command. If it is a narrow, observable operation that agents keep faking badly, write a plugin.

The point is not to make the agent introspective. The point is to make the workflow observable. Once the session becomes a log, repeated mistakes stop being anecdotes. They become engineering input.

db-semantic-mcp Gives AI Agents a Safe Semantic Map of Your Database

Antonio Zhu — Tue, 11 Aug 2026 00:38:27 +0000

AI agents are getting database access before they understand databases.

That is the wrong order.

A real production database is rarely self-explanatory. The important table is not always named orders. The customer table may be called t_bd_customer. A field may carry a business-critical status code that only makes sense if you know the system behind it. A warehouse may split raw operational data, cleaned dimensions, and aggregated facts across schemas with names like ods, dw, and staging. The schema is technically visible, but the meaning is not.

So I built db-semantic-mcp: a small MCP server that gives AI coding agents a safe semantic map of a database.

It exposes table names, column types, comments, sample rows, and LLM-powered schema search. It supports PostgreSQL and SQL Server. It works with MCP-compatible agent clients such as OpenCode, Claude Code, Cursor, and similar tools.

It deliberately does not execute SQL.

That boundary is the point.

The missing layer between agents and databases

Most database integrations for agents start with query execution. Give the model a connection string, add a SQL tool, maybe add a read-only role, and let it ask the database questions.

That can be useful. It is also a big first step.

Before an agent writes or runs a query, it needs to answer more basic questions:

Which tables are relevant?
What do these column names mean?
Which schema contains source data and which contains modeled data?
Is this field a business status, a foreign key, a soft-delete marker, or an internal implementation detail?
When a user says "inventory", "receivables", "customer", or "WIP", what tables should the agent inspect?

Those are not SQL execution questions. They are database understanding questions.

db-semantic-mcp focuses on that layer. It gives the agent enough structure to navigate the database without turning the database into a remote-control surface.

What it exposes

The server provides four MCP tools:

Tool	Purpose
`list_tables`	List database tables with schema names and table comments.
`describe_table`	Inspect columns, types, nullability, and column comments.
`sample_data`	Fetch a small number of example rows from a table.
`search_schema`	Search tables and columns semantically using an OpenAI-compatible LLM.

The first three tools are direct metadata and sampling operations. They let an agent inspect the database the way a developer would: list tables, open one table, look at columns, check a few rows.

The fourth tool is where the semantic layer matters.

search_schema combines a cached schema snapshot with an optional Markdown file that describes your business terms, naming conventions, and database design decisions. The model can then resolve natural-language requests such as:

customer receivables
WIP inventory
sales order
应收账款

into the tables and columns that are likely to matter.

This is especially useful for databases where the table names are technically consistent but not obvious to an agent. ERP databases, legacy SQL Server systems, and large warehouse schemas often fall into that category.

The semantic file is intentionally boring

There is no new ontology format to learn. There is no vector database to deploy. There is no separate catalog service.

You write a Markdown file.

For example:

# Database Semantic Context

## Naming Conventions

- `ods.*` tables contain raw operational data.
- `dw.*` tables contain modeled fact and dimension tables.
- `staging.*` tables are temporary ETL staging tables.

## Business Terms

| Business term | Table(s) |
| --- | --- |
| Customer | ods.bd_customer, dw.dim_customer |
| Inventory | dw.fact_inventory_snapshot |
| WIP / work in progress | dw.fact_wip_by_lot |

## Design Decisions

- Monetary amounts are stored in integer cents.
- `_modified_at` columns are incremental sync watermarks.
- Soft deletes use `doc_status = 'D'`.

That file is loaded into the schema search prompt. It is the bridge between the database's physical structure and the vocabulary developers or business users actually use.

The important design choice is that the semantic layer stays close to the team. It can live next to the project. It can be reviewed like documentation. It can be changed without re-indexing a vector store or migrating a metadata system.

Why no SQL execution?

Because the first safe primitive an agent needs is not always a query tool.

If an agent can execute arbitrary SQL, even read-only SQL, the safety problem becomes larger immediately. You need to think about permissions, row-level access, query cost, data exfiltration, audit logs, and prompt injection through data. Those problems are solvable, but they are not free.

db-semantic-mcp takes a narrower position: give the agent visibility into structure and meaning first.

That makes the tool useful in more conservative environments. A team may be comfortable exposing table metadata, comments, and a few sample rows to an agent long before it is comfortable giving the agent a general SQL execution surface. The server still connects to the database, so it should be configured carefully, but its product boundary is intentionally smaller.

The result is not a text-to-SQL platform. It is the layer before text-to-SQL. It helps the agent understand where it is.

Built for real databases, not demo schemas

The first implementation supported PostgreSQL. The current version also supports SQL Server through the same MCP interface.

The backend is selected from the DATABASE_URL scheme:

postgresql://user:pass@localhost:5432/mydb
sqlserver://user:pass@host:1433?database=mydb&encrypt=disable

That matters because a lot of valuable business data is not sitting in a neat Postgres app database. It is in SQL Server. It is in ERP systems. It is in databases with thousands of tables, inconsistent comments, historical naming conventions, and schemas that only a few people inside the company understand.

For those databases, db-semantic-mcp includes cache controls such as schema filters and table-prefix filters. If a SQL Server database contains thousands of tables but the useful business tables share prefixes like t_pur_, t_sal_, t_stk_, or t_bd_, the schema cache can focus on those areas.

This is not about making a toy database easier to query. It is about making messy real databases navigable by an agent without pretending they are clean.

How an agent uses it

Once registered with an MCP client, the workflow is simple.

An agent can start broad:

list_tables schema=dw

Then inspect a candidate table:

describe_table table=dw.fact_inventory_snapshot

Then look at a few rows:

sample_data table=dw.fact_inventory_snapshot limit=3

Or search semantically:

search_schema keyword="customer receivables"
search_schema keyword="应收账款"

The agent does not need to guess table names from memory. It does not need the user to paste schema dumps into every prompt. It can ask the database metadata server for the relevant context, then use that context in the coding task.

For example, if the task is to modify an ETL pipeline, add a reporting endpoint, or debug a data mapping issue, the agent can first discover the database shape instead of hallucinating it.

That is the value: better grounding before action.

Configuration shape

The server is configured through environment variables:

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
SEMANTIC_FILE=/path/to/SCHEMA.md
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

LLM_API_KEY is only required for semantic search. The metadata tools work without it.

An MCP client can register it as a local server:

{
  "mcp": {
    "db-semantic": {
      "type": "local",
      "command": "pg-semantic-mcp",
      "environment": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname",
        "SEMANTIC_FILE": "/path/to/SCHEMA.md",
        "LLM_API_KEY": "sk-..."
      }
    }
  }
}

The command name still uses pg-semantic-mcp for compatibility with the original PostgreSQL-only version. The package and repository now use the broader db-semantic-mcp name because the server supports multiple backends.

What this is good for

db-semantic-mcp is useful when an agent needs database context but should not start by executing SQL.

Good fits include:

AI coding agents working on backend services connected to PostgreSQL or SQL Server.
Data platform projects where table names and business concepts are not obvious.
ERP and legacy database exploration, especially when schemas are large.
Teams that want agent-assisted development without immediately exposing query execution.
Projects where a lightweight Markdown semantic layer is easier to maintain than a full data catalog.

It is not trying to replace a BI platform, a warehouse catalog, a governance product, or a complete text-to-SQL system.

It is a small missing primitive: let the agent understand the database before it acts on the database.

The broader direction

I think agent tooling is going to split into two categories.

Some tools will make agents more powerful. They will let agents execute, mutate, deploy, administer, and automate more of the system.

Other tools will make agents better grounded. They will expose state, constraints, readiness, history, metadata, and semantics in ways that reduce guessing.

db-semantic-mcp belongs to the second category.

It does not make the agent omnipotent. It gives the agent a map. In real engineering work, that is often the safer and more useful first step.

Project: github.com/chncaesar/db-semantic-mcp

OpenCode Session Framework Internals

Antonio Zhu — Mon, 10 Aug 2026 08:22:40 +0000

The easiest way to misunderstand an agent session is to treat it as a chat API call with a longer memory. Send a prompt, receive a response, append both to a transcript. That is enough for a demo. It is not enough for a coding agent.

I ran into this while reading a small fleet client that drives remote OpenCode instances. The client does very little on the surface: create or reuse a session, send a prompt, wait for the remote agent to become idle, then fetch recent messages. The interesting part is that none of those verbs mean exactly what they mean in a normal request-response API. A prompt does not equal a response. A timeout does not mean failure. A session is not just a transcript. Status is not derived from the last line of text.

That small client is a useful entry point because it exposes the shape of the real system. OpenCode's session design is not one function that calls a model. It is a framework for admitting work, serializing execution, projecting durable state, streaming observations, and letting clients recover when a long-running agent is still in flight.

Primary code references:

opencode-fleet/src/tools.ts
opencode-fleet/src/session.ts
opencode-fleet/src/node.ts
packages/opencode/src/server/routes/instance/httpapi/groups/session.ts
packages/opencode/src/server/routes/instance/httpapi/handlers/session.ts
packages/opencode/src/session/session.ts
packages/opencode/src/session/prompt.ts
packages/opencode/src/session/run-state.ts
packages/opencode/src/session/status.ts
packages/opencode/src/session/processor.ts
packages/opencode/src/server/routes/instance/httpapi/handlers/event.ts
packages/core/src/session.ts
packages/core/src/session/input.ts
packages/core/src/session/run-coordinator.ts
packages/core/src/session/runner/llm.ts
packages/core/src/event.ts
packages/core/src/session/projector.ts

The fleet client follows the desktop-compatible OpenCode API: /session, /session/:id/prompt_async, /session/:id/message, /session/status, and /event. The newer V2/core API exposes the same architectural direction more explicitly through /api/session, /api/session/:id/prompt, /api/session/active, /api/session/:id/event, and the durable SessionInput and SessionEvent pipeline. Both matter because together they show the transition from a working client protocol to a cleaner internal runtime model.

Key Takeaways

If you are building an agent runtime, design sessions as execution containers, not as chat transcripts. A real session framework has to preserve identity, admit work, run one continuation at a time, expose observable status, persist structured messages, and make interruption and recovery normal operations.

Separate session identity from prompt execution. A session can outlive any single prompt. It owns directory, project, agent, model, title, permissions, messages, parts, and runtime state.
Treat prompt submission as admission. The client should be able to submit work and return before the agent finishes. Completion is a separate observation problem.
Serialize execution per session. Multiple prompts may arrive while the agent is busy. The runtime needs a coordinator that runs at most one drain loop per session and coalesces follow-up work.
Expose status as runtime state. Busy, idle, and retry are not reliable if inferred from text. They should come from the execution layer or from an authoritative active-session set.
Use events as the observation boundary. Clients should not poll messages to guess what happened. They should subscribe to session and message events, then keep a local projection.
Persist messages as structured state. Text is only one part. Tool calls, tool results, reasoning, files, snapshots, errors, and step boundaries need identity and lifecycle.
Make timeout, interrupt, and reset distinct. Timeout means the caller stopped waiting. Interrupt asks the runtime to stop work. Reset discards a client-side binding or context. These are different operations.

The Minimal Client Contract

The fleet client is intentionally small. It exposes MCP tools such as fleet_create_session, fleet_send_message, fleet_get_session_status, fleet_get_session_messages, fleet_interrupt_session, and fleet_reset_session. Behind those tools, there are only two main classes.

SessionManager keeps an in-memory map from node name to active session ID. It lazily creates a session on first send, reuses the same session for future prompts, and recreates a session if the server returns 404. OpenCodeNode wraps the remote HTTP API and owns a persistent SSE subscriber that listens to /event.

The important flow is short:

fleet_send_message
-> SessionManager.send
-> get or create session
-> POST /session/:id/prompt_async
-> wait for session.status idle over SSE
-> GET /session/:id/message
-> extract assistant text or tool progress summary

That flow already contains several design choices worth copying.

First, the client binds one long-lived session per remote node. It does not create a fresh session for every prompt. That preserves working context and makes follow-up prompts meaningful.

Second, sending a prompt is asynchronous. OpenCodeNode.sendPromptAsync(...) posts a user message to /session/:id/prompt_async and returns after the server accepts it. The fleet client then waits for status separately. This is the right split. If the same request both submits work and waits for the entire agent loop to finish, the client has no clean way to distinguish "the server accepted my work but the agent is still running" from "the server never accepted my work."

Third, timeout is not treated as failure. SessionManager.send(...) catches TimeoutError, fetches partial messages, marks timedOut: true, and tells the caller the remote agent is likely still running. That is exactly the behavior an agent coordinator needs. In a coding-agent runtime, a slow task is often useful work, not a broken request.

Fourth, reset is guarded. fleet_reset_session checks status and refuses to reset a busy session. This is not just user-interface caution. Resetting while a remote agent is running loses the caller's handle to in-flight work. The agent may still write files, ask for permissions, or finish with output after the caller has thrown away the session ID. A framework should make that hard to do accidentally.

The fleet implementation is not the whole OpenCode session architecture. It is a client-side adaptation. But it shows what the server must provide: stable session IDs, async prompt admission, observable status, message history, interruption, and enough structured message parts to explain progress before final text exists.

Session Creation Is Identity, Not Execution

In the desktop-compatible API, the legacy route group defines POST /session as session.create. The handler eventually calls Session.create(...), which creates a session record with an ID, slug, project, directory, path, optional workspace, title, agent, model, permissions, token counters, and timestamps. It publishes session.created through the event bridge. Projectors then write that session into SQLite.

Nothing has run yet.

That distinction is easy to miss. A session is not "the model is working." A session is the durable container in which work may later happen. It represents a place in the filesystem, a selected agent and model, permission context, and a message history boundary.

The newer V2/core path makes the same idea clearer. SessionV2.Service.create(...) resolves the project for a location, creates a Session.Info, publishes a created event, and returns the stored session. Execution is not part of creation. The session starts idle.

This matters for agent framework design because the session ID becomes the join key for everything else:

user prompts
assistant messages
tool calls
permission requests
question requests
status events
snapshots and diffs
model and agent switches
compaction checkpoints
interrupt and reset operations

If session creation also starts execution, that boundary gets muddy. If a session is only a transcript row, it will not have enough identity to support tooling, permissions, status, or recovery. A good session object should answer: where is this agent working, what policy applies, what model and agent should subsequent turns use, and which durable history does this execution belong to?

Prompt Submission Is Admission

The desktop-compatible async endpoint is /session/:sessionID/prompt_async. Its handler requires the session, then forks promptSvc.prompt(...) into the server scope and immediately returns 204 No Content.

That means the HTTP response does not mean "the assistant finished." It means "the server accepted responsibility for starting the prompt work." The actual work continues in a fiber.

Inside SessionPrompt.prompt(...), OpenCode creates a user message, stores its parts, touches the session, applies any per-prompt tool permission overrides, and then calls loop(...) unless the prompt was marked noReply. The loop is the real execution path.

The V2/core API names the same boundary more explicitly. POST /api/session/:sessionID/prompt calls SessionV2.Service.prompt(...). That service verifies the session, resolves the prompt, chooses a message ID, and calls SessionInput.admit(...). Admission publishes session.next.prompt.admitted as a durable event. Only after the input is durably admitted does the service call execution.wake(sessionID).

This is the key design move: prompt submission becomes durable input admission plus execution wakeup.

That gives the runtime several properties that a direct "call the model now" design does not have.

The prompt has an identity before the model runs. The system can reject duplicate message IDs. It can record that a prompt entered the session even if execution starts slightly later. It can choose not to resume immediately. It can queue or steer inputs. It can replay durable input history into a projected message stream. It can recover from client disconnects because the prompt is not merely an in-memory function argument.

If you are building an agent runtime, this is one of the most important principles to copy. Do not make the user's prompt disappear into a model call. Admit it into the session first. Then schedule execution.

Execution Needs A Per-Session Coordinator

Once prompts can be admitted independently from execution, the runtime needs a rule for what happens when work arrives while the session is already busy.

OpenCode has two implementations that reveal the same idea.

In the desktop-compatible path, SessionRunState keeps a per-session Runner. The runner has states such as Idle, Running, Shell, and ShellThenRun. ensureRunning(...) starts work if idle. If a run is already active, it waits for that active run instead of starting a second one. If shell work is active, it can queue a run after the shell finishes. cancel(...) interrupts the current fiber and returns the runner to idle.

In V2/core, SessionRunCoordinator is smaller and more explicit. It maintains a map from session ID to active entry. wake(sessionID) starts a drain fiber if idle. If a fiber is already running, it sets pendingWake = true. When the active fiber settles successfully, the coordinator starts a successor if a wake was recorded. interrupt(sessionID) marks the entry as stopping, clears pending wake, and interrupts the owner fiber.

That gives OpenCode an important invariant:

one session -> at most one active drain loop

Different sessions can run concurrently. The same session cannot accidentally run two provider turns against the same history at the same time.

This is not an implementation detail. It is the difference between a predictable agent session and a race condition factory. Without a per-session coordinator, two prompts can read the same context, both call the model, both write assistant messages, and both execute tools against the filesystem. In a coding agent, that is dangerous. The second prompt may assume files are unchanged while the first prompt is editing them. Tool permissions and status become ambiguous. The UI cannot honestly say what the session is doing.

The right abstraction is not a mutex around the HTTP handler. It is a session execution coordinator. It should live at the runtime layer, below all clients, so desktop, TUI, MCP clients, scripts, and external tools all obey the same rule.

The Runner Is A Drain Loop, Not One Model Call

The execution loop itself is also larger than one model call.

In the desktop-compatible path, SessionPrompt.runLoop(...) repeatedly sets the session busy, loads compacted history, finds the latest user and assistant state, handles subtasks and compaction tasks, resolves the current agent and model, builds tools, assembles system instructions, converts stored messages into provider messages, and calls SessionProcessor.process(...). The processor consumes the provider stream and updates message parts as text, reasoning, tool calls, tool results, errors, and finish state arrive. If the model asked for tools, the loop continues so the tool results can be sent back to the model.

In V2/core, SessionRunner.run(...) follows the same conceptual shape. It checks pending steer or queue inputs. runTurnAttempt(...) promotes pending input into active context, prepares system context, resolves model and tools, builds an LLM.request(...), streams provider events, publishes structured session events, settles local tools, and continues if tool calls or new steering require another turn.

The naming matters. A good agent runtime does not have a completeChat(...) function. It has a drain loop. The loop drains admitted work until the session reaches a stable idle boundary.

That loop has to deal with continuation conditions:

the model requested tools
tools finished and their results need to be sent back
new steering arrived while a turn was active
queued input is waiting
compaction is required before another provider call
the provider failed before durable assistant output existed
the user denied permission and the loop should stop
the session was interrupted

If those conditions are bolted onto a single request handler, the handler becomes impossible to reason about. OpenCode keeps them inside session execution. Clients submit work, observe events, and interrupt if needed. They do not own the agent loop.

Status Should Come From Execution, Not Transcript Guessing

The fleet client originally has a tempting fallback: inspect messages and infer busy or idle by looking for step-finish parts after the last user message. That kind of fallback is useful for compatibility, but it should not be the primary status model.

OpenCode's desktop-compatible runtime has SessionStatus. It keeps an instance-local map of non-idle sessions. set(sessionID, { type: "busy" }) publishes a session.status event and stores the status. set(sessionID, { type: "idle" }) publishes both session.status and deprecated session.idle, then deletes the session from the map. A missing status means idle.

SessionRunState calls status.set(...busy...) when a runner becomes active and status.set(...idle...) when the runner returns to idle. SessionProcessor sets busy while processing provider streams and sets retry status during retry backoff. The server exposes the status map through GET /session/status, and it also streams session.status events through /event.

The V2/core API exposes the same concept as GET /api/session/active. It returns the set of foreground drains currently owned by this OpenCode process. If a session appears there, it is running. If it is absent, it is inactive.

The lesson is simple: status should come from the execution owner.

Message history is a projection of what happened. It is not the authority for what is currently happening. A session may be busy before the first assistant step appears. A provider may be retrying without writing new visible text. A tool may be running with no final assistant answer yet. A streamed text delta may arrive before the durable final text part. If a client has to scrape messages to infer status, the runtime has failed to expose a basic operational fact.

This is why opencode-fleet keeps a persistent SSE status stream and optimistically marks a session busy immediately after prompt_async returns. There is a race window between prompt admission and the first SSE event. A client that immediately checks status should not conclude "idle" just because the event has not arrived yet.

Events Are The Observation Boundary

OpenCode clients do not need to keep asking, "what changed?" They subscribe.

The desktop-compatible /event endpoint registers an eager listener against EventV2Bridge, filters events by instance directory and workspace, emits a synthetic server.connected, sends heartbeat events, and streams JSON payloads as SSE. The global event endpoint wraps the GlobalBus and carries cross-instance events. The newer server package exposes /api/event for all server events and /api/session/:sessionID/event for durable per-session events.

That gives the desktop app and external clients a common observation model. The app's server-session.ts applies events into a local Solid store. It updates session info on session.created and session.updated, status on session.status, messages on message.updated, parts on message.part.updated, deltas on message.part.delta, permissions on permission.asked, questions on question.asked, and so on. It also reconciles optimistic local messages with confirmed server events.

This local projection is not just for UI polish. It is a fundamental architecture choice. The server owns truth. Clients maintain projections.

That separation solves several problems.

It lets a client show progress before a final response exists. It lets a client reconnect and refresh from durable history when needed. It keeps streaming deltas separate from final durable values. It lets different clients observe the same session without embedding execution logic in each client. It gives external tools a debugging path: subscribe to events, then inspect messages and parts when something looks wrong.

If you build an agent runtime without an event boundary, every client becomes a partial runtime. The UI will poll messages. The CLI will invent a different status heuristic. External tools will guess when work is done. Eventually those guesses disagree.

Messages Are Structured Projections

The most visible artifact of a session is the conversation. But OpenCode does not treat the conversation as plain text.

In the desktop-compatible projection, session messages live as message rows and part rows. A user message can contain text, files, agents, and subtasks. An assistant message can contain text, reasoning, tool parts, step markers, snapshots, patches, retries, compaction parts, and errors. A tool part has a call ID, tool name, input, status, output, metadata, attachments, and timing.

That shape is why opencode-fleet can return useful partial output when a prompt times out. If the assistant has no text yet but tool calls are running, the client can summarize tool activity instead of returning an empty string. It can say the agent is busy and list the tools in progress.

V2/core pushes this further with durable session events and projected messages. SessionInput.admit(...) records prompt admission. SessionInput.promoteSteers(...) publishes session.next.prompted. createLLMEventPublisher(...) converts provider events into session events such as session.next.step.started, session.next.text.delta, session.next.text.ended, session.next.tool.called, session.next.tool.success, session.next.tool.failed, and session.next.step.ended. SessionProjector turns those events into queryable message rows.

This creates three useful layers:

Layer	Role
Durable events	What happened, in order, with session sequence numbers
Projected messages	Query-friendly session state for UI and clients
Client store	Local observable cache, including optimistic and streaming state

That layering is more work than appending text to an array. It is also what makes a coding-agent session debuggable. If a tool failed, you can find the tool call. If a provider streamed text and then failed, you can represent partial output and final error separately. If a permission request blocked execution, it has identity. If compaction changed the context boundary, it is a session event and a message part, not an invisible truncation.

The design principle is that the transcript is a projection, not the source of truth. The source of truth is the session's structured event and message state.

Interrupt Is Not Reset

Long-running agents need lifecycle controls. OpenCode exposes several, and the differences matter.

prompt_async starts work and returns immediately. session.status or /api/session/active tells a client whether work is still running. /session/:id/abort or /api/session/:id/interrupt asks the runtime to stop active execution. Fetching messages shows what has happened so far. Resetting a client binding merely means the client stops using that session ID for future sends.

These operations should not be collapsed.

The fleet client handles this well. On timeout, it does not reset. It tells the caller the agent is still running and recommends checking status, inspecting messages, waiting, or interrupting. fleet_interrupt_session sends an abort signal but does not delete the session or clear the binding. fleet_reset_session discards the cached session ID only after checking that the session is not busy.

That behavior reflects the server-side reality. In the desktop-compatible runtime, SessionRunState.cancel(...) interrupts active fibers and cancels related background jobs. The runner transitions back to idle and status events are emitted. In V2/core, SessionRunCoordinator.interrupt(...) marks the active entry as stopping, clears pending wake, and interrupts the owner fiber. The runner then settles interrupted tools and assistant state.

A reset cannot do that. Reset is a client-side context decision. Interrupt is an execution decision. Delete is a storage decision. Timeout is a waiting decision. If your framework uses one "cancel" or "reset" button for all four, users will eventually lose work or leave orphaned execution behind.

Compatibility Is A Shell Around The Runtime

One subtle part of OpenCode's current codebase is that it has both the desktop-compatible instance API and the newer V2/core API mounted in the same process. The route tree in packages/opencode/src/server/routes/instance/httpapi/server.ts provides legacy routes such as /session/:id/prompt_async and /event, while also mounting the newer @opencode-ai/server handlers for /api/session, /api/event, and related endpoints.

That can look confusing if you read only endpoint names. It makes more sense if you separate protocol compatibility from runtime architecture.

The legacy API exists because clients depend on it. The desktop UI, generated SDKs, compatibility wrappers, CLI paths, and external tools still speak that language. It has concepts such as promptAsync, message.part.delta, and session.status.

The V2/core architecture makes the internal model more explicit. Prompt admission is a durable event. Pending inputs live in SessionInputTable. Execution is coordinated through SessionExecution and SessionRunCoordinator. Session events can be replayed per aggregate. Projectors build structured message rows from durable events.

The lesson for agent-runtime builders is not "copy these exact endpoints." The lesson is to keep the compatibility shell thin. Let old clients keep their contract, but move the runtime toward clearer boundaries: admission, execution, events, projection, and observation.

If compatibility code owns the runtime model, every old endpoint shape becomes a permanent architectural constraint. If the runtime owns the model, compatibility handlers can translate.

What To Copy

If I were designing a session framework for a new coding agent, I would copy these pieces first.

Create sessions independently from prompts. A session should be a durable execution container with location, agent, model, permissions, title, timestamps, and identity. It should be useful before anything is running.

Admit prompts before running them. Give each prompt or user message an ID. Persist it or publish it durably. Only then wake execution. That makes retries, duplicate detection, queueing, and recovery possible.

Run one drain loop per session. Do not let every HTTP request or client call start its own model execution. A coordinator should own session execution and serialize work for that session while allowing other sessions to run concurrently.

Make status authoritative. Either expose a status map or an active execution set. Busy, idle, and retry should be runtime facts, not message-history guesses.

Stream events. Clients should subscribe to server events and maintain projections. Polling can exist as a fallback, but it should not be the core observation model.

Persist structured message parts. Text alone is not enough. Tool calls, tool results, reasoning, files, errors, snapshots, and step boundaries need their own identities and states.

Design lifecycle controls separately. Timeout, wait, interrupt, reset, delete, and fork are not the same operation. Give them separate APIs and make dangerous transitions explicit.

Keep compatibility outside the core. Endpoint names will change. SDK shapes will change. Desktop and CLI needs will differ. The runtime should be stable underneath those clients.

The Core Shape

The simplest useful mental model for an agent session is this:

Session identity
  -> admitted inputs
  -> per-session execution coordinator
  -> agent drain loop
  -> structured events
  -> projected messages
  -> client-side observable state

That shape is more complicated than a chat completion wrapper. But the complexity is paying for real product requirements: long-running work, tool execution, concurrent clients, interruption, retries, partial output, permissions, compaction, and debugging.

The mistake is to start with the provider API and build upward. Provider APIs know how to produce tokens and tool-call requests. They do not know what a session means in your product. They do not know how to serialize work per project directory. They do not know when a client timed out but the agent is still running. They do not know how your UI should reconcile optimistic messages with durable events. They do not know what it means to reset a remote worker safely.

The session framework owns those answers.

OpenCode's implementation is valuable because it exposes that boundary. The model call is inside the session runtime, not the other way around. Prompts are admitted before execution. Execution is coordinated per session. Status is published by the runner. Events are the observation surface. Messages are structured projections. Clients can be thin because the runtime has a real shape.

That is the design principle worth taking: build the session as the agent's operating context. The chat transcript is only one view of it.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

My OpenCode Database Was Mostly Empty Space

Antonio Zhu — Wed, 22 Jul 2026 07:47:16 +0000

OpenCode keeps a lot of useful history.

That is one of the reasons I like it. A coding-agent session is not just a chat transcript. It is a record of what I asked, what the agent did, which tools ran, what failed, what got fixed, and what context existed at the time. I have argued before that the agent session is becoming a log file. I still believe that.

Then I noticed the log file was getting large.

On one machine, ~/.local/share/opencode/opencode.db had grown past a gigabyte. That was not shocking by itself. I use OpenCode heavily. Long sessions produce many messages, tool results, shell outputs, file reads, and state transitions. A local database growing over time is expected.

What was surprising was what SQLite reported after looking inside the file: much of it was not live data anymore.

It was empty space.

The misleading part of deleting data

Most developers learn an intuitive model of storage that is only partly true.

If I delete rows from a database, I expect the database file to get smaller. If I archive old sessions, compact history, or remove records, I expect disk usage to fall. At the application level, that feels right: fewer records should mean fewer bytes.

SQLite does not normally work that way.

When rows are deleted, SQLite can reuse the freed pages for future writes, but it does not necessarily return those pages to the filesystem. The file can stay the same size while containing a growing internal pool of reusable pages. That pool is the freelist.

The important distinction is:

database file size != live data size

The file can be 1.3 GB while the live data is only 525 MB. The remaining 766 MB can be pages SQLite is keeping around for reuse. From SQLite's perspective, that space is available. From the filesystem's perspective, it is still occupied.

That is not corruption. It is not necessarily a bug in the data model. It is how SQLite behaves unless the database is configured and vacuumed in a way that returns free pages to the OS.

For a normal application database, this may not matter. For a local agent runtime that stores every tool-heavy session in one file, it becomes noticeable.

Why OpenCode makes this visible

Agent sessions are unusually good at producing large, bursty storage.

A normal chat app stores messages. A coding agent stores messages plus tool calls, tool results, shell output, file contents, structured parts, todos, events, and session metadata. A single task can contain a surprising amount of durable state.

OpenCode also has session compaction. Compaction is useful for model context management, but it is easy to confuse three different layers:

Layer	What changes
Model-visible context	Older conversation can be summarized behind a checkpoint.
Durable history	Original rows can still exist in the database.
SQLite file layout	Deleted or obsolete pages may remain inside the file as freelist space.

Compaction helps the model continue when context gets too large. It does not mean the database file shrinks. Even when rows are removed by some maintenance path, SQLite may keep the freed pages in the same file.

This is the kind of problem that is easy to misdiagnose if you only look at du -h opencode.db. A large file does not tell you how much live data exists. It only tells you how much disk the file currently occupies.

The first tool I wanted was not a cleaner. It was a measurement.

The useful number is freelist percentage

SQLite already exposes the numbers needed to understand the problem:

PRAGMA page_size;
PRAGMA page_count;
PRAGMA freelist_count;

From those values, the diagnosis is simple:

freelist_bytes = freelist_count * page_size
live_bytes = (page_count - freelist_count) * page_size
freelist_pct = freelist_count / page_count

That gives a more useful report than raw file size:

OpenCode Database Health Report
----------------------------------------------------------
  File size:     1.3 GB
  Page size:     4.0 KB
  Journal mode:  wal
  Auto-vacuum:   OFF (NONE)

Storage
----------------------------------------------------------
  Live data:     525 MB
  Freelist:      766 MB  (56% of file)
  -> VACUUM would reclaim ~766 MB
  -> Estimated result:  ~525 MB

This changes the conversation. The question is no longer "why is the database 1.3 GB?" The better question is "how much of this file is still live data?"

If the freelist is small, there is nothing urgent to do. If half the file is freelist pages, a cleanup can reclaim real disk space.

That became ocdbc: OpenCode Database Cleaner.

Why I did not want a clever cleaner

The dangerous version of this tool would delete sessions.

That is not what I wanted. I did not want a policy engine deciding which conversations were old, stale, low-value, or safe to remove. Agent sessions are evidence. They contain exactly the kind of messy operational detail I often need later: commands, errors, constraints, design decisions, failed attempts, and verification output.

So ocdbc has a narrower job.

It does two things:

ocdbc analyze
ocdbc vacuum

analyze is read-only. It reports database size, live data, freelist space, table sizes, session age distribution, and the largest messages.

vacuum does not decide what history should exist. It asks SQLite to rebuild the database file so unused pages can be returned to the filesystem. The goal is physical cleanup, not semantic deletion.

That boundary matters. A tool that deletes history needs product policy. A tool that reports freelist space and runs a safe SQLite maintenance sequence can stay much smaller.

The safety sequence matters

VACUUM sounds boring until you remember what file it is operating on.

This is the local database for an agent runtime. If OpenCode is running while the database is being rebuilt, I do not want to discover edge cases by corrupting my own session history. If the write-ahead log has committed data that has not been checkpointed into the main database file, I do not want to back up an incomplete view. If the database is already corrupt, I do not want the cleanup tool to make the failure harder to reason about.

So ocdbc vacuum is intentionally conservative.

The sequence is:

Refuse to run if fuser shows OpenCode still has the database open.
Checkpoint the WAL before copying the database.
Run PRAGMA integrity_check before making changes.
Create a timestamped backup.
Open the backup and verify its integrity too.
Set auto_vacuum = INCREMENTAL so future free pages can be reclaimed incrementally.
Run VACUUM to rebuild the file.
Re-enable WAL, because VACUUM can reset journal mode.
Run a final integrity check.

The order is the point.

Checkpoint before backup means the .db file contains committed WAL data before it is copied. Verifying the backup means the fallback is not just a file that happened to exist. Refusing to run while another process has the database open prevents a maintenance tool from racing the application it is trying to help.

There are override flags, but they are explicit:

ocdbc vacuum --force
ocdbc vacuum --skip-fuser --force
ocdbc vacuum --no-backup --force

The default path optimizes for not losing data.

A small tool is enough

The whole package is a single Python module with no runtime dependencies. Installation is intentionally uninteresting:

pip install ocdbc

Then:

ocdbc analyze

If the report shows significant freelist bloat, close OpenCode and run:

ocdbc vacuum

That is it.

The tool does not need a daemon. It does not need to understand model context. It does not need to parse sessions or judge which messages matter. It only needs to expose the maintenance operation I wanted OpenCode users to have available when the database file becomes misleadingly large.

That is the pattern I keep coming back to with agent tooling. The best tool is often not the most intelligent one. It is the one that gives the agent or developer a missing primitive with a tight safety boundary.

For readiness checks, that primitive was wait_for: poll a URL, port, or command until the condition is actually true.

For session review, that primitive was session_reflection: treat recent sessions as evidence instead of disposable scrollback.

For OpenCode database bloat, the primitive is ocdbc: show the difference between live data and empty pages, then run the boring SQLite cleanup correctly.

The broader lesson

AI-assisted development creates new kinds of local infrastructure.

The agent runtime is not just a prompt window. It has tools, permissions, sessions, transcripts, databases, plugins, logs, background state, and failure modes. Once that runtime becomes part of daily work, it needs the same boring maintenance primitives every other developer toolchain needs.

Sometimes the fix is not a better model.

Sometimes it is knowing that your 1.3 GB database contains 766 MB of empty pages, closing the app, checkpointing the WAL, verifying a backup, running VACUUM, and getting your disk space back.

That is not glamorous.

It is exactly the kind of boring tool I want more of.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

OpenCode Tool Calling Internals

Antonio Zhu — Mon, 20 Jul 2026 13:42:59 +0000

This document analyzes OpenCode's tool-calling implementation from the perspective of someone building an agent runtime. The goal is not only to explain how OpenCode happens to call tools today. The more useful question is: what design problems does a real coding-agent runtime have to solve once tool calling moves beyond a demo callback?

Primary code references:

packages/opencode/src/tool/tool.ts
packages/opencode/src/tool/registry.ts
packages/opencode/src/session/tools.ts
packages/opencode/src/session/prompt.ts
packages/opencode/src/session/processor.ts
packages/opencode/src/session/llm.ts
packages/opencode/src/session/llm/ai-sdk.ts
packages/opencode/src/session/llm/native-runtime.ts
packages/opencode/src/permission/index.ts

The conclusions below follow the normal OpenCode session tool path. MCP tools, plugin tools, and the experimental native LLM runtime are included where they reveal the underlying design.

Key Takeaways

If you are building an agent runtime, treat tool calling as a runtime subsystem, not as a provider feature. Provider function calling is only the provider-side way of delivering a tool request. The runtime still has to decide which tools exist, which tools are visible, whether execution is allowed, how progress is represented, how output is normalized, and how the session recovers when execution fails.

Keep an internal tool contract. Do not let OpenAI, Anthropic, AI SDK, MCP, or any one provider define the shape of your runtime tools. OpenCode uses Tool.Def as its internal contract and projects it outward later.
Build a tool catalog, not a static tool list. Tool visibility depends on the agent, model, provider, runtime flags, plugins, MCP clients, and permissions. A serious runtime recomputes the catalog for each turn.
Put permission gates inside execution. Prompt instructions and UI affordances are not enough. The dangerous action must block at the point where the tool would actually touch the filesystem, shell, network, or external server.
Persist tool calls as state. A tool call is not just text in the transcript. It has identity, input, progress, output, attachments, timing, error state, and cancellation behavior.
Normalize provider events before they reach the session layer. Providers and model runtimes disagree about streamed tool inputs, results, errors, and provider-executed calls. The session layer should consume one event vocabulary.
Design for debuggability from the start. Tool call IDs, session IDs, message IDs, permission events, plugin hooks, and durable message parts are not extras. They are what let you answer the basic question: what happened?

Why Tool Calling Needs A Runtime Layer

The smallest tool-calling demo looks simple. The model emits a function name and JSON arguments. The application looks up a local function, runs it, sends the result back, and the model continues.

That design collapses as soon as the agent becomes useful.

A coding agent does not merely call getWeather. It reads files, writes files, applies patches, spawns shell commands, lists project directories, asks questions, starts subtasks, calls MCP servers, and may return images or other attachments. Some tools are safe. Some need approval. Some are available only for certain models. Some are provided by plugins. Some should be hidden from an agent entirely. Some run long enough that the UI needs progress. Some are interrupted halfway through. Some produce outputs too large to fit into the next request.

At that point, provider function calling is not the system. It is only one input boundary. The real system is the layer that turns a model's request into a permissioned, observable, cancellable, durable operation inside an agent session.

OpenCode's implementation is useful because it draws that boundary clearly. Tools are not just callback functions passed to streamText(...). They pass through an internal contract, a registry, a session adapter, an LLM runtime adapter, and a session processor. That layering has cost, but it solves problems a direct callback design usually discovers too late.

How The Pieces Connect

The concrete implementation path is short enough to keep in your head.

SessionPrompt.runLoop(...) creates the assistant message for the current provider turn. Before calling the model, it asks SessionTools.resolve(...) to build the tool map for this exact agent, model, session, permission state, and runtime configuration. SessionTools.resolve(...) pulls tool definitions from ToolRegistry, adapts them into AI SDK-compatible tools, injects Tool.Context, and wires execution through plugin hooks and Permission.ask(...).

Then SessionProcessor.process(...) calls LLM.stream(...). The default runtime passes the prepared tools to AI SDK streamText(...). The native runtime uses a different adapter, but still calls back into the same OpenCode-owned tool execution shape. Runtime-specific stream events are converted into LLMEvent values. SessionProcessor consumes those events and persists text, reasoning, tool calls, tool results, errors, usage, and cleanup state as session message parts.

The spine is:

SessionPrompt.runLoop
-> SessionTools.resolve
-> ToolRegistry.tools
-> LLM.stream
-> LLMAISDK.toLLMEvents or native runtime events
-> SessionProcessor.handleEvent
-> Session.updatePart / Session.updateMessage

That path is also the debugging path. If a tool was missing, start at ToolRegistry.tools(...). If it was visible but executed with the wrong context, inspect SessionTools.resolve(...). If the provider emitted unexpected tool events, inspect the runtime adapter. If the UI shows the wrong state, inspect what SessionProcessor persisted.

Design Principle 1: Keep A Provider-Independent Tool Contract

OpenCode's internal contract lives in packages/opencode/src/tool/tool.ts. A tool definition has an ID, description, parameter schema, optional JSON Schema, execute function, and optional validation-error formatter. The important detail is that this is OpenCode's shape, not the provider's shape.

The parameter schema is an Effect schema. Before any tool implementation runs, the wrapper created by Tool.define(...) decodes unknown model input. If the model emits invalid arguments, OpenCode raises InvalidArgumentsError with a model-facing message that asks the model to rewrite the input. Only decoded input reaches the tool implementation.

The execute function receives a Tool.Context containing the session ID, message ID, tool call ID, active agent, abort signal, prior messages, a metadata(...) updater, and an ask(...) permission hook. That context is the real API a tool author uses. A file-writing tool does not need to know how the TUI handles permission prompts. It only needs to call ctx.ask(...). A long-running tool does not need to know how session parts are stored. It only needs to call ctx.metadata(...).

The wrapper also enforces cross-cutting behavior. It validates arguments, records a Tool.execute span, applies output truncation when the tool has not already done so, and attaches common attributes such as tool.name, session.id, message.id, and tool.call_id.

The design lesson is simple: define the tool contract around your runtime's invariants. Provider schemas, AI SDK tools, MCP definitions, and plugin APIs should be projections or adapters. They should not be the source of truth.

Design Principle 2: Build A Runtime Tool Catalog

OpenCode's ToolRegistry is not just a map from names to functions. It is a catalog builder.

It starts with built-in tools such as read, glob, grep, edit, write, task, webfetch, todo, skill, shell, and apply_patch. It then scans configured directories for project tools under {tool,tools}/*.{js,ts} and loads plugin-provided tools from the plugin service. When a plugin provides a tool, the registry immediately wraps it in OpenCode's internal tool contract, so the rest of the runtime can treat it like a built-in tool.

The registry then filters and shapes that catalog for the current turn. For example, the web search tool is not always visible. OpenCode exposes it only when the selected provider supports it, or when runtime flags such as Exa or parallel search are enabled. Experimental tools appear only when flags allow them. GPT-family model handling can choose apply_patch and hide edit and write. The task tool also gets a dynamic description listing the subagents the current agent is allowed to call, so the model knows which subagent_type values are valid. Before any tool is exposed to the model, plugins also get a tool.definition hook that can adjust its description or schema.

This is also how OpenCode exposes subagent delegation. A subagent is not normally launched by a hidden scheduler. The model sees the task tool, reads the dynamically listed subagent_type options, and decides whether delegation is useful for the current turn. If it calls task, the runtime executes that tool and starts the selected subagent. In other words, delegation itself is modeled as tool calling.

Permissions also affect visibility. A broad deny rule can hide a tool before the model ever sees it. Edit-like tools are grouped under edit, while MCP resource tools are grouped under read. This avoids advertising tools that are already forbidden by policy.

The design lesson is that an agent's tool list is a runtime projection. It depends on who the agent is, what model is running, what session permissions apply, what plugins are installed, what external servers are connected, and what feature flags are enabled. If you make the tool list static, those concerns will leak into individual tools or into prompt text.

Design Principle 3: Put Permissions Inside Execution

OpenCode's permission boundary is not a sentence in the system prompt. It is an Effect that can block tool execution.

Tools call ctx.ask(...) with a permission name, path or resource patterns, metadata, and optional always patterns. The write tool asks for edit permission and includes a diff. The shell tool parses commands, resolves paths, asks for bash, and separately asks for external_directory when a command reaches outside the project boundary. Read-like tools ask for read over path patterns. MCP resource tools ask for read over mcp:server:uri patterns.

Permission.ask(...) checks three sources of authority: the agent's configured permission rules, any session-level permission overrides, and approvals granted earlier in the current runtime process when the user chose an "always allow" option. If every pattern is allowed, execution continues. If any pattern is denied, execution fails. If the runtime needs user input, it creates a pending request, publishes Permission.Event.Asked, and waits on a Deferred. When the client replies, Permission.reply(...) publishes Permission.Event.Replied and resolves or rejects the waiting tool.

This design matters because permission is enforced at the point of action. A model can ask for a shell command. The UI can render a prompt. But the shell command does not run until the permission service resolves. The approval path is part of execution, not decoration around it.

The design lesson is to make safety a blocking dependency of side effects. If permission is implemented only as model instruction, client UI, or precomputed filtering, eventually some tool path will bypass it.

Design Principle 4: Persist Tool Calls As State

A tool call is a long-lived operation, not a line of assistant text. It begins when the provider says the model wants a tool, but it may pass through streamed input, permission waiting, execution, progress updates, output truncation, attachment handling, cancellation, and failure cleanup before the model sees a result. If a runtime only stores the final tool result as transcript text, it loses the operation boundary.

That boundary matters. The UI needs to show that a tool is running before it finishes. A permission rejection needs to be different from a tool crash. A cancelled run needs to mark unfinished calls instead of leaving them as ghosts. A debug trace needs to answer which tool ran, with what input, under which assistant message, and what output or error it produced. None of that can be reliably reconstructed from prose.

Durability adds another benefit: interruption and restart become tractable. If tool calls are persisted as structured records, a runtime can inspect what was pending, running, completed, or failed after a crash or cancellation. That does not mean it should blindly re-execute tools after restart; tools may have side effects. It means the runtime has enough state to make an explicit recovery decision: retry only if safe, mark an abandoned call as interrupted, or rebuild the model-visible history with accurate completed results. Without durable tool state, restart logic has to infer too much from partially written text.

OpenCode handles this by persisting tool calls as assistant message parts. SessionProcessor owns the state machine. When the normalized event stream reports tool input or a tool call, the processor calls ensureToolCall(...). If this is the first event for a call ID, it creates a tool part with state pending. When the tool-call event arrives, the part becomes running and records the tool name, input, timing, and provider metadata. When a result arrives, completeToolCall(...) writes completed with output, metadata, title, attachments, and end time. When an error arrives, failToolCall(...) writes an error state.

The basic state model is:

pending
-> running
-> completed | error

There is also cleanup behavior. At the end of processing, unresolved tool calls are given a short chance to settle. Remaining calls are marked as interrupted errors with Tool execution aborted and metadata indicating interruption. This keeps the transcript from containing permanently running calls after cancellation or stream failure.

The exact state machine is small, but the design choice is large. Tool calls are durable operation records. Text is what the model reads later. State is what the runtime needs to render, cancel, inspect, retry, and debug the operation.

Design Principle 5: Normalize At Runtime Boundaries

An agent runtime has two unstable boundaries around tool calling. One boundary faces the model provider. The other faces tool implementations. Both are messy.

Providers do not all describe tool activity the same way. One runtime may stream tool input deltas. Another may report only a completed call. A provider may mark a call as provider-executed, surface a tool error as a stream event, or wrap usage and metadata in provider-specific fields. If those event shapes leak directly into session state, every downstream system has to understand provider quirks: UI rendering, debugging, retries, compaction, permissions, and persistence.

Tool outputs have the same problem from the other side. One tool may return a string. Another may return a structured object. An MCP tool may return text, an image, or a resource blob. A file-oriented tool may return attachments. A shell tool may return too much output. If the runtime lets every output shape flow straight into history, the next model request becomes unpredictable and the UI has no stable contract to render.

OpenCode handles the provider side with an event normalization seam. The default runtime path uses AI SDK streamText(...); the experimental native runtime lowers selected requests into @opencode-ai/llm. The session processor does not consume either runtime directly. Both paths converge on LLMEvent. For the AI SDK path, packages/opencode/src/session/llm/ai-sdk.ts converts fullStream events into OpenCode's event vocabulary: text deltas, reasoning events, step events, tool input events, tool calls, tool results, tool errors, provider errors, and finish events. The native runtime emits the same downstream vocabulary.

OpenCode handles the tool-output side with a normalized result shape: title, metadata, output text, and optional attachments. The tool wrapper applies output truncation unless the tool already reports truncation metadata. SessionTools.resolve(...) assigns IDs to attachments and binds them to the current session and assistant message. SessionProcessor can normalize image attachments before persisting the completed result. MCP resource helpers convert text, images, and resource content into explicit text output plus durable file attachments, while unsupported or oversized binary content is omitted with a visible explanation.

The design choice is not just convenience. It protects the rest of the runtime from two sources of drift: provider event drift and tool output drift. Once a provider stream has become LLMEvent, session persistence does not care whether the call came from AI SDK or the native runtime. Once a tool result has become OpenCode's output shape, the model, UI, and database do not care whether it came from a built-in tool, plugin tool, or MCP server.

The lesson for runtime builders is to normalize at every boundary where external variability enters. Do not let provider-specific event shapes or tool-specific output shapes become your session model. Convert them into runtime-owned contracts before they become history, UI state, or the next model input.

What OpenCode Gets Right

It separates internal tool semantics from provider mechanics. Tool.Def is the source of truth. AI SDK tools, MCP tools, plugin tools, and native runtime tools are adapters around that contract.

It makes tool visibility contextual. The runtime does not pretend every agent and every model have the same capabilities. The tool catalog is rebuilt for the current session turn.

It puts permission checks where side effects happen. Sensitive operations block inside execution, and the approval flow is represented as runtime events.

It persists tool lifecycle explicitly. A tool call has state, input, timing, output, metadata, attachments, and failure information. This is essential for UI, debugging, and recovery.

It creates a stable event seam between model runtimes and session state. AI SDK and native runtime differences are normalized before SessionProcessor handles them.

It leaves room for extension. Plugins and MCP servers can add tools without bypassing the same broad execution framework.

Where The Design Is Still Expensive

The cost of this design is complexity.

A tool call can pass through many layers: tool definition, registry projection, provider schema transformation, session adapter, permission gate, plugin hooks, LLM runtime, event normalization, and session processor persistence. When behavior is wrong, the bug may live in any one of those seams. A tool can be defined correctly but hidden by permissions. It can be visible but transformed into a provider schema the model handles poorly. It can execute successfully but return an output shape that is later truncated. It can be interrupted after the provider already emitted a partial event.

The design also relies on tools asking for the right permissions. The framework can block ctx.ask(...), but it cannot magically know which resources an opaque tool input will touch. The shell tool is the clearest example. A file tool receives a structured filePath, so it can ask for permission over that path directly. A shell tool receives an opaque command string. Before it can ask precise permissions, it has to parse that string, identify filesystem-related commands such as rm, cp, mv, mkdir, cat, or cd, extract path arguments, expand home and environment references, resolve relative paths against the working directory, and detect paths outside the project boundary. Only then can it ask for permissions such as bash or external_directory with meaningful patterns. Without that parsing step, the runtime would either approve every shell command too broadly or block useful commands too often.

Safety moves from a prompt problem to a tool implementation problem. That is better, but it is still work.

Provider behavior remains an input boundary. OpenCode normalizes provider events after it receives them, but it still depends on the provider or runtime to surface tool calls, results, errors, and cancellation in a usable way. The native runtime can reduce some provider coupling, but it does not remove the need for careful adapter design.

The design lesson is not that every agent runtime should copy OpenCode's exact files. The lesson is that once an agent can change a real project, tool calling becomes infrastructure. Infrastructure has seams, state, and failure modes.

The provider tells you what the model wants. The runtime is responsible for making that request safe, observable, and recoverable.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

OpenCode V2 Compaction Internals

Antonio Zhu — Fri, 17 Jul 2026 11:26:41 +0000

This document analyzes the OpenCode V2 compaction implementation. The conclusions are based on the V2/core code path in the OpenCode repository. When code, comments, and documentation disagree, this document follows the current code behavior.

Primary code references:

packages/core/src/session/compaction.ts
packages/core/src/session/runner/llm.ts
packages/core/src/session/history.ts
packages/core/src/session/context-epoch.ts
packages/core/src/session/runner/to-llm-message.ts
packages/core/src/session/message-updater.ts
packages/core/src/config/compaction.ts

This document only covers the V2/core compaction path. It does not cover the V1 compatibility /compact implementation or the DCP plugin's compress tool.

Key Takeaways

OpenCode V2 compaction is a durable checkpoint-and-retry mechanism, not a relevance-pruning system. It is a last-resort survival mechanism — avoid triggering it whenever possible.

Avoid compaction. Once triggered, all older context is compressed into a hardcoded 4_096-token summary. Details that do not fit are not recovered. The session survives, but its continuity depends entirely on what the summary captured.
Compaction is size-triggered, not relevance-triggered. It runs when the request estimate exceeds the context threshold — regardless of how important or irrelevant the conversation is. The system has no concept of message importance.
Three hardcoded limits control quality. Tool/shell output is truncated at 2_000 chars (TOOL_OUTPUT_MAX_CHARS), summary output is capped at 4_096 tokens (SUMMARY_OUTPUT_TOKENS), and neither is configurable. Only buffer and keep.tokens are exposed in the config schema.
History is never deleted, but old rows are no longer loaded. Old messages remain in durable storage. After compaction, future model requests start from the checkpoint and do not see older rows through normal provider calls.
Media content is not preserved in model-visible context after compaction. Images and videos from before the checkpoint are reduced to text metadata ([Attached image/png: screenshot.png]). The original binary data remains in durable history, but the model cannot see visual content from before the checkpoint through normal provider requests.
Compaction is safe but blunt. It never deletes history, never leaves a half-compacted session, and prevents infinite retry loops. But it makes no attempt to distinguish important facts from noise when summarizing older context.

Core Design

Long coding-agent sessions produce long conversation histories. Tool calls, tool results, shell outputs, file reads, and multi-turn reasoning accumulate. Eventually the full provider request exceeds the model's context limit. Deleting old messages would lose durable history. Compaction solves this with a checkpoint strategy: create a new message that represents older history, then let future runner attempts use that message as a starting boundary.

V2 compaction separates three layers that would otherwise be conflated:

Layer	What it is	What compaction does to it
Durable history	Full session record in `SessionMessageTable`	Not changed. Old rows remain.
Active history	The slice of messages loaded for a provider attempt	Shortened. Future loads start from the latest `type: "compaction"` checkpoint.
Model-visible context	What the model actually receives in a request	Replaced. Older context becomes `<summary>` + `<recent-context>` inside a `<conversation-checkpoint>` block.

This three-layer design is the key insight. Compaction does not shrink the database. It changes the default projection of history used to call the model, and it renders old context through a generated summary rather than replaying every old message.

How It Works

Trigger

Compaction has two trigger paths.

Automatic path. Before each normal assistant-response provider attempt, the session runner estimates the full provider request size and compares it against the current model's context window:

estimated_request_tokens > model_context_limit - max(output_tokens, compaction_buffer)

The default compaction buffer is 20_000 tokens. With a 128_000 token context window and default output limit, the threshold is approximately 108_000 tokens.

Recovery path. If the provider returns a context overflow error and the current turn has not yet produced durable assistant output or tool execution, OpenCode runs one recovery compaction and retries. This path handles cases where the local token estimate did not prevent a provider-side overflow. The overflow recovery path runs at most once to avoid looping.

Both paths eventually call the same implementation: compactAfterOverflow(...) in packages/core/src/session/compaction.ts.

Split History Into `head` And `recent`

Compaction divides active session history into two parts.

First, existing type: "compaction" messages are ignored. The remaining structured session messages are converted into plain text. The helper function is named serialize(...) in the code, but this is a text conversion step, not binary serialization:

user messages become [User]: ... plus attachment descriptions.
assistant text becomes [Assistant]: ....
assistant reasoning becomes [Assistant reasoning]: ... when reasoning text exists.
assistant tool calls become [Assistant tool call]: tool(input).
completed tool results become [Tool result]: ....
failed tool calls become [Tool error]: ....
system updates become [System update]: ....
synthetic context becomes [Synthetic context]: ....
shell messages become [Shell]: command + output.

Tool output and shell output are truncated to 2_000 characters. This limit is hardcoded as TOOL_OUTPUT_MAX_CHARS in packages/core/src/session/compaction.ts:14 and is not exposed through the compaction config schema. Binary and media content is not embedded as base64. Images, videos, and attachments are reduced to text metadata such as [Attached image/png: screenshot.png]. The compaction summary request is always text-only. A non-multimodal model can still run the summary request because it receives only text labels. However, it cannot infer visual or binary content unless that content was already described elsewhere in text.

The converted text is then split by walking backward from the latest message. The default recent-context budget is 8_000 tokens from DEFAULT_KEEP_TOKENS. Recent converted text within this budget is kept as recent. Older converted text becomes head.

The newly selected recent is not summarized in the same compaction run. It is stored directly in the checkpoint and later rendered as <recent-context>. The newly selected head is what gets summarized.

Generate The Summary

The summary prompt is built by buildPrompt(...). Its job is not just to shorten text. It tries to preserve the working state needed for a coding-agent session to continue.

When there is no previous checkpoint, the prompt starts with:

Create a new anchored summary from the conversation history.

When a previous checkpoint exists, the prompt asks the model to update the anchored summary rather than blindly stacking independent summaries:

Update the anchored summary below using the conversation history above.
Preserve still-true details, remove stale details, and merge in the new facts.

The prompt then includes a fixed Markdown template tuned for session recovery:

## Objective — what the user is trying to accomplish.
## Important Details — constraints, decisions, assumptions, exact context needed to continue.
## Work State — completed work, active work, blockers.
## Next Move — the next concrete action after retry.
## Relevant Files — file paths that would otherwise be easy to lose during summarization.

The prompt rules require the model to keep every section, use terse bullets, preserve exact paths/symbols/commands/errors/URLs/identifiers, and avoid mentioning that context was compacted. The last rule matters: the generated checkpoint should read like normal historical context, not an explanation of an internal maintenance operation.

The context passed into the summary is: previous checkpoint recent, when one exists, plus the newly selected head.

The summary request uses the same input.model as the current provider attempt, with no tools and a maximum of 4_096 output tokens. This limit is hardcoded as SUMMARY_OUTPUT_TOKENS in packages/core/src/session/compaction.ts:15 and is not exposed through the compaction config schema. Even if the model supports larger output, the cap is always 4_096. There is no separate specialist compaction model in the current V2 core path.

This is a significant constraint. A long session may have accumulated detailed information — file paths, commands, error messages, design decisions, constraints, test results — across many turns. All of that older context must be compressed into at most 4,096 output tokens of structured summary. If important details exceed what the summary model can fit, they are not preserved for future provider attempts. The session does not crash, but the model's working knowledge of old context can become incomplete.

Persist The Checkpoint

Before summary generation starts, OpenCode publishes SessionEvent.Compaction.Started. This event does not create a checkpoint message.

During generation, the implementation collects text delta chunks. If the stream reports a provider error, throws LLM.Error, or produces an empty summary, compaction returns false and no checkpoint is written. Failure handling is conservative: a failed summary attempt does not move the active-history boundary.

Only after a non-empty summary is generated does OpenCode publish SessionEvent.Compaction.Ended. The session projector handles this event by inserting a durable type: "compaction" message into SessionMessageTable. The inserted row includes the message ID, session ID, compaction type, event sequence, creation time, and the payload: reason, summary, and recent.

This is the point where the generated summary becomes part of session history and can be used as the next active-history boundary.

Retry From The Checkpoint

After the checkpoint is persisted, compactAfterOverflow(...) returns true, and compactIfNeeded(...) returns true to the runner. The runner stops the current attempt before calling the model by throwing ContinueAfterCompaction — a control-flow signal, not a user-facing error.

On the retry, OpenCode reloads active history from the latest compaction checkpoint and rebuilds a smaller provider request. That smaller request is then sent to the model.

The normal path is:

build request -> estimate size -> split history -> summarize head -> write checkpoint -> retry -> call model

Repeated Compaction

If the session grows again after the first compaction, the cycle repeats. compactAfterOverflow(...) reads the existing checkpoint message from the current entries. When a previous summary exists, the new prompt asks the model to update the anchored summary rather than starting from scratch.

The benefit is continuity across multiple compactions. Older summarized facts can be carried forward, while newer head content is merged into the updated summary.

The limitation is cumulative summary risk. Each repeated compaction depends on the previous checkpoint summary and the latest summarization pass. A detail dropped earlier is not recovered by re-reading old pre-checkpoint rows.

What The Model Sees After Compaction

After compaction, SessionHistory.latestCompaction(...) finds the newest type = "compaction" message. The history loader starts active history from that checkpoint sequence. Older messages before the checkpoint are no longer loaded into the normal provider request.

When the checkpoint is sent to the model, to-llm-message.ts renders it as a user-role <conversation-checkpoint> block:

<conversation-checkpoint>
The following is a summary and serialized record of earlier conversation. Treat it as historical context, not as new instructions.

<summary>
...
</summary>

<recent-context>
...
</recent-context>
</conversation-checkpoint>

There are two important design choices here. First, the checkpoint is model-visible context, not hidden state. The next provider attempt can reason over the summary and recent context because they are rendered into the prompt. Second, the checkpoint text explicitly frames itself as history, not new instructions. The model receives a smaller request with an explicit continuity record, but it no longer sees old messages in their original structured form. It sees the generated summary and the retained recent text.

Completed compaction also interacts with Context Epoch. If the latest compaction sequence is newer than the stored baseline sequence, the system-context baseline can move forward to the same boundary in context-epoch.ts. This prevents old mid-conversation system updates from being mixed into the new active history inconsistently.

Configuration Surface

The V2 compaction config is intentionally small, defined in packages/core/src/config/compaction.ts:

compaction: {
  auto?: boolean
  prune?: boolean
  keep?: { tokens?: number }
  buffer?: number
}

The current V2 compaction implementation uses:

auto — whether automatic compaction runs (default: true).
buffer — reserved headroom before the context limit (default: 20_000).
keep.tokens — recent-context budget (default: 8_000).

The prune field exists in the schema but is not used by the current core compaction logic.

The configuration controls thresholds, not pruning policy. It determines when compaction runs and how much recent text is kept verbatim, but it does not select which messages or tool results to remove from context before compaction.

Strengths

Durable, not destructive. Original session messages remain in SessionMessageTable. Compaction appends a new checkpoint message. Nothing is deleted. This makes the checkpoint auditable and replayable.

Safe retry boundary. The runner can stop the current attempt and rebuild the next provider request from the checkpoint. This avoids replaying the full old conversation.

Simple mental model. Older context becomes summary; the newest converted text becomes recent. The summary prompt enforces a coding-agent-oriented structure — Objective, Work State, Next Move, Relevant Files — tuned for session recovery rather than generic prose compression.

Recent exact context preserved. The most recent converted text is not summarized in the same compaction run. It is stored directly as recent, reducing the chance of losing exact details from the latest work.

Conservative failure mode. If compaction cannot produce a completed checkpoint — summary prompt too large, provider error, empty summary — it does not move the active-history boundary. The session remains in its pre-compaction state.

Checkpoint framed as history, not instruction. The <conversation-checkpoint> text explicitly declares itself historical context, not new instructions. This is simple prompt engineering that reduces the risk of the model misinterpreting the compacted summary as fresh user intent.

Small, predictable configuration surface. Only three fields control behavior in the current core path: auto, buffer, and keep.tokens. There are no complex pruning policies to tune or debug. The behavior is threshold-driven and easy to reason about.

Limitations

The summary output bottleneck — this is the most important weakness. The summary output limit is hardcoded at 4_096 tokens (SUMMARY_OUTPUT_TOKENS in packages/core/src/session/compaction.ts:15) and not configurable. A long coding session can span tens of thousands of tokens of tool outputs, file reads, error messages, design decisions, shell commands, and reasoning chains. All of that older context — everything except the most recent ~8_000 tokens — must be compressed into at most 4_096 tokens of structured summary.

This means any detail that does not fit into the summary is not automatically recovered from durable history during future provider requests. The model's working knowledge of old context becomes only what the summary captured. File paths can be dropped. Error messages can be paraphrased into uselessness. Design decisions can be collapsed to a bullet point. The session does not crash, but its continuity depends entirely on the quality of the 4k-token summary.

This is the fundamental reason to avoid triggering OpenCode V2 compaction whenever possible. Compaction is a survival mechanism, not an optimization.

Size-based trigger, not relevance-based. Compaction starts when the estimated provider request is too large, or after a provider-side context overflow. It does not run because a message is stale, duplicated, low-value, or off-topic. The system has no concept of message importance.

Coarse summarization of older context. Older converted text is summarized as a block. The implementation does not rank individual messages, tool results, command outputs, or file reads by relevance. It treats all pre-recent history as summarization material.

Shallow tool output handling. Large tool and shell outputs are truncated to 2_000 characters during text conversion. This limit is hardcoded (TOOL_OUTPUT_MAX_CHARS) and not configurable. A single important line in a large log file may be truncated away, while a verbose but low-value message may consume recent-context budget.

Media content is not visible to the model after compaction. Images, videos, and other binary attachments are reduced to text metadata such as MIME type and filename during text conversion. Once media falls behind the compaction boundary, future model requests see only the checkpoint text. The original binary data remains in durable history, but it is no longer part of model-visible context through normal provider requests.

Checkpoint is irreversible for active context. After compaction, future model requests normally depend on the checkpoint summary and recent context for older information. Mistakes, omissions, or distortions in the summary become the model's only working knowledge of old context.

No deterministic pruning. The config schema includes prune, but current V2 core compaction does not use it. The implementation is checkpoint summarization, not a policy engine for removing specific tool results, errors, or repeated file reads.

Claims The Current V2 Code Does Not Support

Based on the current V2/core code, do not claim that:

V2 supports user-selected manual compaction ranges.
V2 uses a hidden compaction agent.
V2 uses a separate smaller model for compaction.
V2 performs deterministic pruning of old tool results.
V2 keeps the last N turns.
V2 deletes historical messages.

The reliable claim is more specific: V2 automatically creates a summary checkpoint when a normal provider attempt is too large, or when provider overflow recovery succeeds before side effects.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

A ⭐ on GitHub means a lot!

My Agent Kept Writing sleep Loops. So I Gave It a Better Primitive

Antonio Zhu — Sat, 11 Jul 2026 02:19:09 +0000

I deployed a change, and the agent needed to confirm the new version was live before running a smoke test. So it wrote what agents always write in this situation:

for i in $(seq 1 40); do sleep 3; curl -s http://host/health && break; done

Then it read the output, saw the old version still serving, and declared the deploy done anyway — because the loop had exited on the first curl that returned anything, not the first one that returned the right thing. I had watched a variant of this play out a dozen times. The agent either polls too few times and gives up early, or hard-codes a sleep 120 and blocks the whole session on a fixed guess, or exits on a 200 that carries a stale body. Every time, it re-derives the same fragile loop from scratch, because there is nothing better sitting in its toolbox.

Why agents reach for sleep

An agent acts through the tools it has. Give it bash, and "wait until the server is ready" collapses into "sleep and hope," because a fixed sleep is the cheapest thing the shell offers. It has no primitive for readiness — no verb that means "keep checking this condition, on a sensible cadence, until it holds or you give up." So it fakes one, and the fake is worse in every dimension: it doesn't know how long to wait, it doesn't know what "ready" actually looks like, and when it fails it throws away everything it observed on the way down.

That last part is the real cost. A hand-rolled loop that times out tells you nothing. The agent is left to run another probe just to find out why the first forty failed — a human-speed round trip through the clipboard, which is exactly the distance I keep trying to shorten between an agent and the ground truth it can't see.

The primitive

So I wrote opencode-waitfor, a zero-dependency plugin that adds one tool, wait_for. You install it by adding one line to opencode.json:

{ "plugin": ["opencode-waitfor"] }

The tool infers what kind of target it's watching. A URL with a scheme gets polled over HTTP; a bare host:port gets a TCP connection check; anything else runs as a shell command. Three shapes of "is it up yet," one verb:

wait_for http://localhost:3000
wait_for localhost:5432 timeout 10
wait_for http://host/health expect { json_match: { status: ok, version: abc123 } }

That last one is the case that started this. After deploying commit abc123, the agent waits until /health reports that version — not any response, the correct one. The stale-body deploy I opened with simply cannot pass.

And when it does time out, it returns the last thing it saw: the final HTTP status and body, or the last command's exit code and output. The agent gets to diagnose from the failure it already has, instead of firing a fresh probe to reconstruct it.

I've written before that the job left to a human, when the agent writes more code than you can read, is standing at the boundary and shortening the distance to ground truth. Usually that's a manual act. Sometimes you can make it structural — hand the agent a primitive shaped like the thing it kept faking, and the bad behavior stops being something you prompt against and starts being something it can't easily do. A tool changes what an agent reaches for more reliably than any instruction telling it to reach for something else.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

Six Laws for Talking to AI

Antonio Zhu — Thu, 02 Jul 2026 01:15:10 +0000

I recently opened a SQLite file — the local session log from OpenCode, the AI coding tool I use every day. 192 sessions, 8,471 messages, 89 million input tokens. Total cost: \$518.

But cost per token is the wrong metric. I wanted to know: how much of what I said was wasted?

So I wrote some queries. I counted every message where I said "不对," "不行," "不是," "不不" — the Chinese equivalents of "no, wrong, not that, stop." I counted sessions where I forked the same conversation and started over. I looked at how many messages were shorter than ten characters. I had six sub-agents analyze the six longest sessions independently, pulling out every instance where I corrected the AI, repeated myself, or sent an instruction so vague the AI had to guess.

The number that stopped me: 60% of my sessions were forked from an older one. I was restarting more conversations than I was finishing. For every two user messages in my worst session, I started a new session.

The rest of this article is what I found. Six patterns. Six fixes. All measurable.

Data Snapshot

Metric	Value
Total sessions	192
Total messages	8,471 (7,109 AI, 1,366 me)
Sessions with a parent (forked)	115 (60%)
Explicit correction messages	67 (4.9% of my messages)
Messages mentioning push/commit	132
Primary model	deepseek-v4-pro (125 sessions)
Sessions above 100 messages	4 (capped at 164)

Four sessions hit triple-digit message counts. The longest — a deployment migration to a new server — ran 164 messages. I said "get my approval first" four times in that session alone. I said "use GitHub Actions, not manual commands" five times. No one else was in the room. I was repeating myself to a machine.

But that 60% fork rate cuts both ways, and I have to be honest about the other side of it. The human in me is lazy. I hate starting new sessions. A fresh session means I have to re-explain the project, re-establish the rules, re-load the mental model. So I don't. I cram unrelated tasks into one session until it becomes a junk drawer. Deployment config, CSS refactoring, database schema changes, and a React component all in the same thread. By message 80, the AI has no idea what we're working on anymore, and neither do I. The context window might technically hold 200K tokens, but attention is not a buffer — it's a spotlight, and my spotlight is painting six walls at once.

The 60% fork rate isn't a disciplined practice. It's a symptom. I fork when I'm frustrated, and I don't fork when I should. Both are failures of context discipline.

Law 1: The gap between knowing and writing is the whole cost.

Everyone knows AI forgets. The interesting question is not does it forget — it's how long do you wait before fixing it.

Across six sessions, I corrected the AI for the same rule violations 27 times before writing a single line to my config file. Not 27 times across months. 27 times where I already knew the pattern, already had the fix in my head, and just didn't stop to write it down.

Rule	Corrected in chat	Messages between first correction and AGENTS.md write
"Get my approval before acting"	4 times	43
"All operations must use GitHub Actions"	5 times	52
"Talk business concepts, not code"	4 times	54
"Remove project-specific details"	4 times	31

The server migration session is the cleanest example. I told the AI "get my approval before acting" on message 1. By message 48, it had forgotten. I said it again. At message 62, the AI pushed code without confirmation — I said it a third time, with profanity. At message 63, ten minutes later, it happened again. I finally wrote the rule to AGENTS.md around message 80.

The waste wasn't the 4 corrections. The waste was the 79 messages between "I know this should be a rule" and "this is now a rule."

Every person who uses AI coding tools knows that writing rules fixes things. The thing I didn't know until I counted: I average 36 messages between knowing and writing. I don't have a knowledge problem. I have an execution latency problem.

The fix: After every single correction, ask: does this rule apply to future sessions? If yes, write it now. Not after this task. Not after this session. Now. The cost of writing is ten seconds. The cost of not writing is the rest of the session.

Law 2: Assess the blast radius. Every time.

Six sessions. Four tirades. Every one followed the same script: I give an instruction involving modification or deletion. The AI starts changing files without telling me what. Something breaks that I didn't expect. I discover the damage and lose my temper.

Specifics: rewriting a website footer and deleting the social links in it. Deleting an entire RSS feed when I only asked to filter old articles. Manually running commands on a production server. Claiming a file exists when it doesn't.

My AGENTS.md already says push and deploy require explicit user confirmation. I wrote that after the server migration disaster. But the rule is too narrow. It only covers git. It doesn't cover rewrites, bulk replacements, folder restructures, or production commands — all of which share the same asymmetry: three seconds to break, thirty minutes to fix.

Here is the thing I missed: this is not a special AI rule. This is the same principle you apply before any production change with a blast radius larger than one file.

We don't let teammates push to production without a diff. We don't approve a database migration without reviewing which tables it touches. We don't run terraform apply without reading the plan first. The AI is no different — except that it's faster and has less judgment. An intern who can type at 10,000 WPM. The engineering discipline that keeps production safe is the same discipline that keeps an AI session from spiraling.

Before I started counting, I thought "ask the AI to confirm" was about trust. It's not. It's about blast radius. The AI proposed a change to my website footer. One file. What's the worst that could happen? The footer appears on every page. That's 100% of the site. One file, full blast radius. The AI doesn't understand that. You do.

The fix: Before any operation that touches more than one file or any file with a cross-cutting footprint, the AI must list every file it will touch and every change it will make. Then wait for confirmation. This is not a negotiation with a coworker. It's a pre-flight checklist. The same instinct that makes you read terraform plan output should make you read the AI's change list. Same discipline. Same muscle.

Law 3: Send the full spec. Not one sentence at a time.

My worst sessions all share a shape: I start with a rough idea, then refine it through seventeen messages. The AI follows each micro-adjustment, but the overhead of each round trip compounds fast.

Here is a real example, anonymized:

"I need a search feature."
"It should filter by name."
"Email too."
"Partial match, not exact."
"Show results in a dropdown."
"Debounce the input by 300ms."
"Start."

Seven messages. Here is the same spec as one message:

Search feature: typeahead dropdown. Filter by name and email, partial match.
Debounce input at 300ms. Show results below the search bar.

Two messages would have done it. I spent five extra messages hand-holding the specification because I hadn't completed it in my own head before typing.

This happened in every long session. The paywall discussion took 18 messages (cancel → no, restrict → wait, AI is paid too → defer). The server migration plan changed direction three times (fully migrate → partially migrate → open a new VM instead). None of these decisions were bad. But each mid-flight change of direction forced the AI to recompute context that had already been settled, which meant it forgot things discussed earlier — which meant I had to re-explain them.

The fix: Before sending a feature request, write the full spec in a text editor. Fields. Constraints. Edge cases. Interactions. Then send it once. The thirty seconds you spend typing to yourself are worth five rounds with the AI.

Law 4: An instruction under ten characters is a puzzle.

In my longest technical session — building a rules-checking tool — 72% of my messages were under fifty characters. 19% were under five characters.

Here is what I actually sent:

What I typed	What the AI had to guess
`change`	Change what? Code? Plan? Naming?
`clean up`	Clean which directory? Which files?
`do it.`	Do which option?
`symbolic link`	From where to where?
`check-rules`	Run the tool? Check a file? Create it?

Each two-word instruction cost one to three clarification rounds. The AI would propose options. I'd pick one. Total waste per instance: two to four messages. In a 74-message session, I estimate these cost me about fifteen rounds.

The interesting thing is that I knew exactly what I meant when I typed "change." The context was clear to me. The problem is that context lives in my brain, not in the chat. The AI can only act on what's in the text.

The fix: Before sending, ask: if someone read this instruction with zero prior context, could they execute it? If the answer is no, add a sentence. "change" becomes "Add input sanitization to the form submission handler." Same idea. Seven more words. Zero guessing rounds.

Law 5: A bug in file A is a bug in files B through Z.

A session where I was deploying multiple services taught me this. Each service had its own CI config file. Service A's deployment failed — missing a network setting. I pasted the error log. The AI fixed Service A.

Service B's deployment failed. Same error. Different file. I pasted the log. The AI fixed Service B.

Service C's deployment failed. Same error. I lost my patience. "You didn't listen," I said. "I told you to fix this."

The AI had never been told to fix all config files. It had been told to fix the one I pasted, twice. I was angry at the AI for doing exactly what I asked.

A similar thing happened in another project: a validation bug existed in both the frontend and backend. I fixed the backend, deployed, and the error came back. The frontend had the same logic, untouched.

The fix: After identifying a bug in one file, the next instruction should be: "Check all files in this category for the same issue." Not "fix this one." One sentence prevents the slow drip of identical errors.

Law 6: "This" and "all" are not the same thing. Say which.

I asked the AI to add input validation to a module. "Validate the email field," I said. The AI validated email — and only email. I meant all fields on the form. But I had said "this field." The AI took me literally.

Same thing with error handling: "add try-catch to this function" got me one function. I wanted it across the entire module. Three rounds to converge.

In both cases I had said "this" — this field, this function — when I meant "every field in the module," "every function that calls an external API." The AI applied the constraint to the one thing I named. I thought the context made my intent obvious. It didn't.

Another case: I told the AI to add rate limiting to one API endpoint, intending it as a pattern for the whole service. The AI added it to one endpoint. I said "no, all of them." Two rounds. If I had started with "add rate limiting to all endpoints," done in one.

The fix: If a constraint applies to more than one output, start with "all." If it applies to one, start with "this one." Explicit scope costs zero tokens and saves three corrections.

The Compounding Asset

None of these laws are about prompt engineering. They are about systematizing your own communication patterns. The real insight from 192 sessions is not that I needed better prompts. It's that I needed a process for not repeating myself.

AGENTS.md is not a file you write once. It's a muscle you exercise after every correction. The engineer who talks to AI for a hundred sessions and writes nothing down has the same information as session ten. The one who writes a rule after every correction has a compounding asset. Every new session starts with the accumulated wisdom of every previous correction. The AI catches up to your intent faster. You repeat yourself less. The sessions get shorter, the output higher quality, and the four-letter words drop to zero.

That's the asymptote worth chasing.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

I Reverse Engineered a Closed-Format App. Everything Was in SQLite.

Antonio Zhu — Fri, 26 Jun 2026 16:47:14 +0000

I had accumulated over two thousand notes in Youdao Cloud Note over several years. When I decided to move to Obsidian, the first thing I checked was the export feature. There wasn't one. No batch export, no single-note export, nothing in the Mac client.

So I went looking for the local data.

Where The Data Was

On macOS, Youdao Cloud Note stores its data here:

~/Library/Containers/ynote-desktop/Data/Library/Application Support/ynote-desktop/

Inside that directory, organized by account email, were three SQLite databases:

<account>.db         # note metadata, folder hierarchy
<account>-content.db # note content (old editor)
<account>-search.db  # search index

And a file/ directory with 16 subdirectories arranged by the first character of each file ID, holding the new editor's local files. Everything was unencrypted.

What The Database Contained

The main database had two critical tables:

note — the note catalog. Key columns: fileId (UUID), title, parentId (folder reference), orgEditorType (0 for the new block editor, 1 for the old plain editor), entryPath (path to the local file), createTime (Unix timestamp in seconds), and deleted (NULL meant not deleted).

note_book — the folder tree. Folders were not in note at all. They lived in a separate table with their own fileId and parentId fields, forming a tree you could traverse with BFS.

The content database held a contenttable with a content field, but the field was truncated to around 150 characters — just enough for search snippets. The real content for old-editor notes lived here too, with variable lengths.

Where the content actually was depended on which editor wrote the note:

orgEditorType	Editor	Content source
0	New (block editor)	`entryPath` → local file
1	Old (plain)	`contenttable.content`

The local files came in two formats: JSON (449 of them) and plain Markdown (1,832).

The JSON Block Tree

The new editor stored notes as a block tree in JSON. Each block followed this structure, with the actual keys being cryptic integers:

"6" → block type (p=paragraph, h=heading, co=code, t=table, im=image, l=list, q=quote, hr=divider)
"4" → properties (heading level, code language, image URL, etc.)
"5" → array of child blocks
"7" → inline text segments with "9" format markers (b=bold, i=italic, li=link, il=inline code, etc.)

Walking the "5" array recursively converted the entire tree to Markdown. The core renderer was under 200 lines.

Three Things That Wasted My Time

The __compress__ flag. Ten JSON files had "__compress__": true. I spent an hour trying to uncompress them with LZString before realizing the "5" array was still just a plain array — not a compressed string. The flag had been set but never used.

Deleted is NULL, not 0. Every note with deleted IS NULL had been a living note. WHERE deleted = 0 returned nothing. This is standard SQL but easy to miss when you're scanning thousands of rows for anomalies.

The timestamp is in seconds. 1484115955 is January 11, 2017. If you treat it as milliseconds and divide by 1000, you land in 1970. I did that once.

A Dead-End That Wasn't

The contenttable.content field was consistently 150 characters. This looked like a deliberate truncation to defeat extraction. But the actual content was never supposed to be in that column — the new editor stored everything in local files referenced by entryPath. The content column was just a search index. Once I followed the entryPath trail, I had the full text of every note.

What The Script Does

The whole thing is a single Python file. It connects to the three SQLite databases, walks the folder tree, maps every note to its content source, converts JSON blocks to Markdown when needed, and writes the output organized by folder.

git clone https://github.com/chncaesar/youdao-to-obsidian.git
cd youdao-to-obsidian
pip3 install beautifulsoup4
python3 youdao_migrate.py

The script auto-detects your account and data directory. Output goes to ~/Desktop/obsidian/ by default. Each note gets a .md file with YAML frontmatter preserving the original title, creation date, and source ID.

I also bundled a Claude Code Skill in the repo — drop it into ~/.claude/skills/ and saying "export my Youdao notes" triggers the whole pipeline without remembering flags.

What Came Out

The final export: 2,285 notes across 253 folders. Mixed Chinese, English, and code content with no encoding issues. Tables, code blocks, images, lists, and blockquotes all converted correctly from the JSON block tree. Some notes were empty bodies with attachments only, handled gracefully.

Open ~/Desktop/obsidian as an Obsidian vault and everything is there.

Why This Worked

The most interesting part of this project was not the parser or the block converter.

It was the realization that a closed-format application with no export feature had been storing all my data in plain, unencrypted SQLite files, with a documented-enough block structure that could be reverse-engineered in an afternoon.

Two thousand notes. Years of writing. The application offered no way to take them out. They were never locked in. I just hadn't looked.

GitHub: github.com/chncaesar/youdao-to-obsidian

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

DEV Community: Antonio Zhu

OpenCode Needs Memory, Not Another Background Pipeline

The gap between instructions and history

A memory layer the active agent owns

Why Markdown is a feature

Install it in one configuration block

What this plugin does not try to solve

The useful middle ground

Codex Memory Internals: What It Remembers, Who Decides, and How It Compares to OpenCode

Key Takeaways

The Pipeline I Found

Phase 1: A Model Decides What A Rollout Taught

Phase 2: A Model Rewrites The Global Memory

What Add, Update, Delete, And Forget Mean

User Authority Is Present, But Indirect

The Read Path Closes The Loop

What Codex Memory Is Not

Codex Versus OpenCode

Where Other Memory Systems Put The Decision

Agent-Directed Memory

Background Memory Pipelines

Temporal And Learned Policies

The Trust Boundary Is The Real Architecture

What Runtime Builders Should Copy

Source Map

OpenCode Memory Internals

Key Takeaways

A Better Mental Model

Layer One: Ambient Instructions

What /init Actually Does

A Narrow Provider-Prompt Exception

The V2 Instruction Path

Layer Two: Durable Session History

Layer Three: Bounded Working Context

What OpenCode Does Not Implement

Why The Simpler Design Is Defensible

What Agent Runtime Builders Should Copy

The Agent Session Is the New Log File

The part we do not review

A session is telemetry

The plugin

Why this belongs in the plugin ecosystem

Start with one repeated failure

db-semantic-mcp Gives AI Agents a Safe Semantic Map of Your Database

The missing layer between agents and databases

What it exposes

The semantic file is intentionally boring

Why no SQL execution?

Built for real databases, not demo schemas

How an agent uses it

Configuration shape

What this is good for

The broader direction

OpenCode Session Framework Internals

Key Takeaways

The Minimal Client Contract

Session Creation Is Identity, Not Execution

Prompt Submission Is Admission

Execution Needs A Per-Session Coordinator

The Runner Is A Drain Loop, Not One Model Call

Status Should Come From Execution, Not Transcript Guessing

Events Are The Observation Boundary

Messages Are Structured Projections

Interrupt Is Not Reset

Compatibility Is A Shell Around The Runtime

What To Copy

The Core Shape

My OpenCode Database Was Mostly Empty Space

The misleading part of deleting data

Why OpenCode makes this visible

The useful number is freelist percentage

Why I did not want a clever cleaner

The safety sequence matters

A small tool is enough

The broader lesson

OpenCode Tool Calling Internals

Key Takeaways

Why Tool Calling Needs A Runtime Layer

How The Pieces Connect

Design Principle 1: Keep A Provider-Independent Tool Contract

What `/init` Actually Does

Split History Into `head` And `recent`