OpenCode TaskMemory

Why I built it

I built OpenCode TaskMemory because agentic coding work rarely fits into one clean pass. A useful workflow often has exploration, planning, implementation, validation, and review steps, with different agents carrying different parts of the job.

I wanted those steps to have a small durable handoff layer. Instead of asking every agent to keep all context in its prompt, the plugin stores session-scoped markdown files that can be written, read, appended, listed, and deleted by name.

What it does

The plugin registers with OpenCode and exposes six tools: currentSession, write, append, read, list, and deleteMemory. I kept the tool set narrow so agents can create compact evidence packets, implementation notes, validation findings, or follow-up instructions inside a known session.

The storage format is plain markdown. I chose that because it keeps memory inspectable by humans, easy to diff, and easy to pass between agents without introducing a database or hosted service.

The handoff loop I wanted: each agent writes durable markdown context instead of hoping the next step remembers it.

Technical shape

OpenCode TaskMemory is a TypeScript OpenCode plugin exported as TaskMemoryPlugin and published as @cdgmx/opencode-taskmemory. I designed the public setup path to stay small: install the package, register it in opencode.json, and use the tools inside OpenCode.

Storage root resolution is explicit: the plugin checks OPENCODE_TASKMEMORY_ROOT and otherwise falls back to os.tmpdir()/opencode/task/memory. Session IDs use the ses_ prefix that matches OpenCode runtime context. Repository evidence also shows .changeset/, .github/workflows/, assets/, and test/ directories, plus local dogfooding through a file:// plugin URL.

Handoff as a timeline

I do not think of TaskMemory as one big notes folder. I think of it as a timeline of packets: evidence, decision, implementation notes, validation results, and follow-ups. Each agent should leave the next one a smaller, cleaner surface than the full chat history.

The workflow I optimized for: one agent writes a packet, the next agent reads the packet, and the session boundary keeps the work from bleeding into another task.

That model also explains why the API is intentionally boring. write, append, read, list, and deleteMemory are enough for predictable handoffs. Anything broader starts to look like arbitrary filesystem access, which is not what I wanted this plugin to become.

Key implementation decisions

• I used markdown files so handoff context remains visible and portable.
• I scoped memory by session to avoid accidental cross-task contamination.
• I exposed a narrow memory API instead of a broad filesystem capability.
• I kept the storage root configurable for local, CI, and plugin-test environments.
• I used Changesets for package release workflow.

Current status

OpenCode TaskMemory is an open-source plugin with no live deployment because its runtime surface is OpenCode itself. Public repository evidence shows published package releases, with v0.3.1 identified as the latest version during research.

I treat the project as a handoff layer, not a replacement for durable product documentation or a team knowledge base.

What I would improve next

I would add more examples for explorer-to-brain, brain-to-implementer, and implementer-to-validator handoffs. I would also document retention guidance for local memory directories and add optional safeguards around memory names, stale sessions, and file size.