opencode-claude-memory: Instructions file for Codex

AGENTS.md

OpenCode plugin that replicates Claude Code's persistent memory system. TypeScript on Bun; published to npm as compiled dist/ via semantic-release. One package serves both plugin APIs: OpenCode ≥ 1.18.29 (V1 server entry; the dual { id, server, setup } default export needs 1.18.29) and OpenCode 2.x (@opencode/cli, V2 setup entry, tested on 2.0.22).

Structure

src/
├── index.ts                      # Dual entry: default export { id, server, setup } (V1 server = createMemoryPlugin, V2 setup = createV2Setup)
├── config.ts                     # PluginOptions zod schema (strict) + CLAUDE_CONFIG_DIR → MemoryConfig; fixed agent names
├── agents.ts                     # Host-independent hidden agent defaults (memoryAgentDefaults: prompt/steps/allowedTools), MEMORY_TOOL_NAMES
├── tools.ts                      # MemoryToolSpec[] for memory_save / delete / list / search / read (zod/v4 args), wrapped per host; results carry their own titles
├── host/
│   ├── types.ts                  # MemoryHost interface (readTranscript / listSessions / runFork / generate), TranscriptMessage, SDK_READ_TIMEOUT_MS
│   ├── generate.ts               # buildGeneratePrompt: a generate request as text, schema in the prompt (V2 always, V1 after a StructuredOutputError)
│   ├── v1/                       # OpenCode 1.18.29+ (`server` entry, @opencode-ai/plugin)
│   │   ├── plugin.ts             # createMemoryPlugin: parseConfig → MemoryStore → V1 host → coordinators → Hooks
│   │   ├── sdk.ts                # Type aliases derived from @opencode-ai/plugin (client, events, messages) + unwrapData
│   │   ├── host.ts               # createV1Host: MemoryHost over the V1 client (deadlines, directory query, tool sandbox)
│   │   ├── fork.ts               # runForkSession: create → prompt(timeout) → abort-on-timeout → delete
│   │   ├── agents.ts             # AgentRegistry / buildAgentDefaults: defaults merged under user `agent.<name>` in the `config` hook
│   │   ├── coordinators.ts       # V1RecallCoordinator / V1ExtractionCoordinator: V1 event + message translation
│   │   ├── messages.ts           # getLastUserQuery / buildTurnID / extractRecentTools / surfaced-memory keys (V1 messages)
│   │   ├── ignore.ts             # ignore / resume over V1 messages, stripAutoMemoryParts (by marker)
│   │   ├── selector.ts           # V1 selector wrappers (child session, structured output)
│   │   ├── tools.ts              # MemoryToolSpec → Hooks["tool"]
│   │   └── log.ts                # createLogger: client.app.log wrapper
│   └── v2/                       # OpenCode 2.x (`setup` entry, @opencode/plugin)
│       ├── plugin.ts             # createV2Setup: tools (codemode: false), agent.transform, hooks, event loop, cleanup
│       ├── agents.ts             # Permission-rule sandbox [*:*:deny, memory_x:*:allow, ...user rules]; host baseline stripped; permissions probe; forkSessionRules
│       ├── host.ts               # V2Host: MemoryHost over ctx.session / generate.text / agent lookup
│       ├── fork.ts               # runV2Fork: create → prompt → wait → context → remove; interrupt on timeout
│       ├── events.ts             # V2SessionEvents (location filtering, busy/idle) + consumeEvents (resubscribe)
│       ├── transcript.ts         # V2 messages → TranscriptMessage
│       └── log.ts                # File logger <stateDir>/opencode-memory.log, rotated at LOG_MAX_BYTES
├── store/
│   ├── frontmatter.ts            # THE memory file format: MEMORY_TYPES, parseFrontmatter (30-line limit), buildFrontmatter
│   ├── paths.ts                  # Pure: validateMemoryFileName (sub-paths), sanitizePath, findCanonicalGitRoot, resolveMemoryRoot
│   ├── scan.ts                   # THE scanner: MemoryHeader/MemoryEntry, defaults decided once, manifest, surfaceKey
│   ├── indexFile.ts              # MEMORY.md minimal line-level upsert/remove + truncateEntrypoint
│   └── MemoryStore.ts            # Resolves paths once; list/read/save/delete/search/scan/readIndex; stateDir
├── prompt/
│   ├── sections.ts               # Claude Code prompt text ports (memoryTypes.ts / memdir.ts)
│   └── systemPrompt.ts           # buildMemorySystemPrompt(store, recalled, opts); AUTO_MEMORY_MARKER
├── recall/
│   ├── selector.ts               # Host-independent LLM selection: prompt, schema, parseSelectedMemories
│   ├── turn.ts                   # Ignore / resume phrase rules + surfaced-key parsing
│   ├── format.ts                 # recallSelectedMemories / formatRecalledMemories / truncation / age warning
│   └── RecallCoordinator.ts      # Per-session turn state, prefetch with bounded wait, session-scoped ignore, TTL eviction
├── extraction/
│   ├── prompts.ts                # EXTRACT_PROMPT / AUTODREAM_PROMPT (only copies)
│   ├── state.ts                  # extraction-state.json (watermarks, autodream gate), atomic writes, v1 lock migration, posixCksum
│   ├── lock.ts                   # Cross-process maintenance lock: token ownership, heartbeat, reap-lock guarded stale recovery
│   ├── autodream.ts              # Gate + consolidation fork
│   └── ExtractionCoordinator.ts  # Idle debounce → serial queue → incremental fork via MemoryHost; start-up catch-up; recordSave
└── util/
    ├── log.ts                    # Host-independent Logger type, LOG_SERVICE, getErrorMessage
    ├── ownedSessions.ts          # Plugin-owned child sessions with grace-period release
    ├── exclusiveFile.ts          # Atomic create-if-absent (tmp + hard link) and the short cross-process file lock
    ├── timeout.ts                # withDeadline() (bounded SDK calls with an AbortSignal) / withTimeout() (no signal, V2)
    └── legacyShellHook.ts        # Read-only detection of v1's shell hook in rc files

test/
├── helpers/index.ts              # temp dirs, makeStore/makeConfig/makePlugin (env + home injected), mock clients, message builders
├── helpers/processWorker.ts      # real worker processes for the cross-process state/lock tests
├── helpers/v2ctx.ts              # scriptable mock of the V2 plugin context (setup(ctx)); records every host call
├── v2/                           # V2 entry tests (setup, tools, agent transform, hooks, events, forks)
├── *.test.ts, store/, recall/, extraction/   # unit + plugin-level tests (bun test)
└── evals/                        # task evals: memory-on vs memory-off system prompts (see test/evals/README.md)