Skip to content

Latest commit

 

History

History
339 lines (234 loc) · 26.3 KB

opencode-adapter.md

File metadata and controls

339 lines (234 loc) · 26.3 KB

OpenCode Adapter

OMMS includes an OpenCode plugin. It runs the same shared memory engine as the Pi extension. Both hosts read and write one store for each project. So Pi can find memories that OpenCode captured, and OpenCode can find memories that Pi captured.

  • The package supports the OpenCode V2 plugin API (native plugins list). The package loads under OpenCode V2 only. See ADR-048.
  • The plugin id is always omms, whatever the npm package name.

Installation

Run npx om-memory-system@latest setup. It finds OpenCode, shows what it will do and asks once. See CLI: setup. It runs opencode plugin add om-memory-system for you and adds the cli.json entry described below when that file exists. Then restart OpenCode and run opencode service restart. Check the result with npx om-memory-system@latest doctor. OpenCode 2.0.22 or later is needed for every feature.

To do the same by hand, add the package to ~/.config/opencode/opencode.json (%USERPROFILE%\.config\opencode\opencode.json on Windows):

{ "plugins": ["om-memory-system"] }

You can run opencode plugin add om-memory-system instead.

opencode plugin list and opencode plugin update also read ~/.config/opencode/cli.json. Add the same entry there, and keep any other keys in that file:

{ "plugins": ["om-memory-system"] }

Without it, opencode plugin update reports Plugin is not configured: om-memory-system. Restart OpenCode after you change the configuration.

What setup does to cli.json

opencode plugin add writes only opencode.json for OMMS. It does not write cli.json, so setup adds the entry itself, with these rules:

  • It edits an existing cli.json only. It never creates the file. OpenCode creates cli.json, and when the file is absent the first start of OpenCode V2 moves old tui.json settings into it. A file that OMMS made would stop that move. If the file is missing, start OpenCode once and run setup again. Do not create the file by hand.
  • It adds the string om-memory-system at the end of plugins, or adds a plugins key when there is none. Every other key, entry, comment and the formatting stay as they are. It writes the file in one step.
  • It reads the file again just before it writes, so a change made while setup ran is kept. A file that already has the entry by then is left alone.
  • When cli.json is a symbolic link (for example from GNU Stow or Home Manager), it writes to the file the link points to. The link stays a link, and the file keeps its permissions.
  • It leaves the file alone when an entry already names om-memory-system in any form, for example om-memory-system@6.4.0.
  • It changes nothing when the file is not valid JSON or when plugins is not a list. It then prints the manual step.

The file is $XDG_CONFIG_HOME/opencode/cli.json when XDG_CONFIG_HOME is set, and ~/.config/opencode/cli.json otherwise.

From a local checkout (development):

  1. Build and pack the plugin with the command below.
  2. Install the tarball the same way OpenCode installs a published package.
bun install && bun run build && npm pack

scripts/verify-nested-onnxruntime-fixture.mjs shows the install layout that CI checks for a packed build.

The omms-memory skill

The package ships the omms-memory skill. The plugin adds it to OpenCode, so you do not copy any files.

  • The plugin adds the skill to OpenCode's skill list. Start it by name with /omms-memory.
  • The skill tells the agent to search memory with the memory tool before it debugs or investigates, and when you refer to earlier work. The memory tool description gives the same instruction.

See Using memory: The omms-memory skill.

The omms-remember skill

The package ships the omms-remember skill beside omms-memory. The plugin adds both the same way.

  • OpenCode v2: start it with /omms-remember.
  • It saves a short snapshot of the session with the memorise mode of the memory tool and reports the ms- ID. OpenCode passes its session ID to the tool, so a repeat snapshot can replace the earlier one when memorisationRepeat is replace.

See Using memory: The omms-remember skill.

Uninstall

  1. Run opencode plugin remove om-memory-system. With OpenCode 2.2.6 it removes the entry from opencode.json and from cli.json. Open cli.json and remove the entry by hand if it is still there.
  2. Stop the login item. OpenCode starts the web app at sign-in while webServerAutoStart is true, and each OpenCode start installs the item again. Set "webServerAutoStart": false in ~/.config/omms/omms.jsonc, then run npx om-memory-system@latest web uninstall. The command also sets that value and removes the item.
  3. Restart OpenCode and run opencode service restart.

Your memories stay in ~/.omms/data. Delete that folder only when you want to lose them.

Configuration

The plugin reads the same configuration files as the Pi extension:

  1. ~/.config/omms/omms.jsonc (global). If this file does not exist, the plugin reads the legacy ~/.config/opencode/opencode-mem.jsonc.
  2. <project>/.opencode/omms.jsonc (project overrides). If this file does not exist, the plugin reads the legacy <project>/.opencode/opencode-mem.jsonc.
  • Storage, embedding, privacy, deduplication, scopes, and thresholds are shared.
  • storagePath defaults to ~/.omms/data. So both hosts use the same store for the same project, unless you change it.

OpenCode-specific options:

{
  // Model for automatic capture and profile learning. "inherit" follows the
  // session's model. Omit both to use the external API when it is configured,
  // otherwise the session's model.
  "opencodeProvider": "openai",
  "opencodeModel": "gpt-5.6-luna",
}

The plugin chooses the capture model with the same rule as Pi (see Configuration: Choosing the model):

  1. opencodeProvider/opencodeModel, if set.
  2. The external API (memoryModel/memoryApiUrl/memoryApiKey), if configured.
  3. The session's model.
  • The provider name must appear in opencode providers list.
  • The model must return JSON that matches the schema in the prompt.
  • If the OpenCode model fails and the external API is configured, the plugin uses the external API. The terminal interface shows a "Using fallback provider" toast.

Each model call is one text generation through the OpenCode plugin context (ctx.generate.text):

  • The call creates no session, and it uses no agent or tool.
  • OpenCode owns the sign-in, so a host model needs no key.
  • Old versions of OMMS left sessions titled omms capture. The plugin ignores them and the importer skips them.

Each capture attempt writes a metadata line to the OMMS log. It can also write a full trace. See Configuration: Capture diagnostics.

The OpenCode plugin does not run a web server inside the session. At start it checks for the shared web app (http://127.0.0.1:4747). If one answers, the plugin uses it. If none answers, it starts one om-memory-system web in the background and shows one toast with the address in the terminal interface. If another program holds the port, the notice says so. Set webServerEnabled to false to keep the web app off. See Web UI.

The web app has no OpenCode session, so the page cannot use OpenCode's signed-in models. Web imports offer only the external API, the Health page skips the OpenCode model test, and Retry now does not retry OpenCode's waiting turns. Live capture, profile learning, automatic backfill, terminal imports, and /import in OpenCode keep working with OpenCode's models.

History backfill (automatic history import) uses opencodeBackfillModel. See Configuration: Automatic history import and login web app.

Lifecycle mapping

OpenCode hook omms behaviour
setup Load shared config for the project directory, remove old capture traces, update the web login item when webServerAutoStart is set, warm storage and embeddings, read connected providers, register the OpenCode backfill model resolver, the profile model, and the import models, start automatic backfill when autoBackfill is on, check for the shared web app and start it when none runs
command Register the /memory-import-opencode-history command and the omms-memory and omms-remember skills
prompt + context Record the prompt once OpenCode admits it; semantic retrieval injected as a delimited <omms-retrieval> system section. The context hook also records the session model when capture follows it (opencodeModel is inherit)
session.idle event After 10 seconds of quiet, capture every uncaptured prompt in the session; run daily maintenance (also with capture off), then profile learning. A session.created event starts the capture retry drain. The plugin only reads events for its own directory
compaction Restore the session's own memories after compaction and after resume
command Run /memory-import-opencode-history; see opencode-history-import.md
memory tool Shared add/memorise/memorize/recall/search/profile/list/forget/help plus migrate/list-shards/export/import
skills tool Shared skill-learning modes list/ideas/draft/evidence/propose/proposals/show/apply/reject/undo/help. Arguments: mode, skill, idea (name, description), folder, state, order, id, limit, content, summary, evidence. A draft saves a pending proposal and changes no file; evidence then propose let the agent fix a skill with no external API call; apply records the agent. See the skills command.

Daily maintenance

After the idle capture, OMMS runs daily maintenance at most once a day in each OpenCode process. It runs with capture on or off.

  • It always removes old capture attempt records, old capture retry rows and old cleanup undo records, and compacts the prompt database.
  • It deletes memories by age only when you turn on Delete old memories automatically in the Memory cleanup card. That writes autoDeleteOldMemories: true to the global config file. The default is off.
  • An older config file with "autoCleanupEnabled": true deletes nothing. See Configuration: Memory cleanup.

Config problems

When OMMS cannot read the config file, or cannot use a value in it, it uses the default, or turns a risky feature off, and keeps running. At plugin start the terminal interface shows one OMMS settings toast per problem, for example "OMMS cannot read ~/.config/omms/omms.jsonc: on line 4, column 3, a comma is missing." The warning names the file and line, or the key and the values it accepts. Fix the file. For a key that a Settings card can change, the notice also points to the Settings page.

Notices

The OpenCode V2 server plugin has no toast API. It sends its notices to the terminal interface over plugin RPC, and the terminal interface shows each one as a toast. Without a terminal interface (opencode serve, OpenChamber), nothing shows them.

Plugin RPC events reach only a terminal interface that listens at that moment. The OpenCode background service often starts the server plugin before the terminal interface, so the server keeps each notice until a terminal interface claims it (claim in src/v2/notice-rpc.ts). The terminal interface claims the waiting notices when it loads, and again at each notice event. The terminal interface confirms each notice (ack) after its toast shows, so a notice whose toast failed stays for the next claim. A failed claim, toast or confirmation is tried again on a short timer, five times at most. A failed notice event is sent again three times at most. Each notice shows once, in the order the server sent it. The server keeps at most 20 notices that no terminal interface has confirmed. Only one terminal interface should be attached, because each one shows the notices it claims.

The notices are:

  • captured memories (showAutoCaptureToasts)
  • changes to the fallback provider, and errors (showErrorToasts)
  • profile updates (showUserProfileToasts)
  • config problems, the web app address or start failure, and automatic import progress

When the web app cannot start, the plugin writes a notice that names the cause and the fix. Pi and Claude Code use the same wording.

  • port-busy: the notice names the port and says to stop the other program, or to set webServerPort in the global config to a free port.
  • no-runtime: the notice says to install Node 22.14 or later, then start a new session.

The terminal interface shows the first-run notice once per computer. It says what OMMS does on its own and how to turn each part off. See Configuration: First-run notice. The server plugin also writes it to its console at each start until a terminal interface has shown it. It does not send it over plugin RPC, because the terminal interface would then show it twice.

The footer status below shows the state of OMMS in the terminal. Pi reports the same events through its footer status and notifications.

Footer status

OpenCode 2.0.22 and later load the plugin's ./tui entry. It shows OMMS's state in the prompt footer, like Pi:

  • omms: ⧖ at start, then omms: ✔ when the web app answers on webServerPort.
  • omms: ✘ web app off when the web app does not answer. Capture and retrieval keep working.
  • omms: ✘ when the footer cannot start its status check.
  • · <version> available when npm has a newer release and OMMS does not install it (local checkout, pinned version, or a failed update). A toast also names the update command once per start.
  • · <version> installed, restart after OMMS installs the newer release in the background and finds the new version on disk. A toast tells you to restart OpenCode and run opencode service restart, because the background service keeps the old copy loaded. While the update installs, a toast says so. The background service also runs the update check, so OpenCode without the TUI (for example OpenChamber or opencode serve) updates too. It shows no notice. When the update command ends with success but the new version is not on disk, the footer keeps · <version> available and a toast names the update command.

The plugin checks npm at start and every 6 hours. When npm has a newer release, it runs opencode plugin update om-memory-system in the background. Set OMMS_DISABLE_UPDATE_CHECK=1 to turn the check and the update off. See Updating and upgrading.

OpenCode 2.2 and later store each update in a new folder, ~/.cache/opencode/npm/om-memory-system@latest/<timestamp>/, about 900 MB each. When the OpenCode background service starts, OMMS removes the older OMMS folders in the background. It keeps the running folder, every newer folder, the folder in ~/.omms/runtime.json, and any folder without a readable version. It removes nothing while the running folder is less than 24 hours old. A folder that OMMS cannot remove stays. Each pass writes one OpenCode cache clean-up log record with counts only.

The footer reads only the health route and the npm registry's latest version. It sends nothing about your sessions.

Recall rows

On OpenCode V2, OMMS searches memory for each prompt and adds the matches to the model's system context. The same ./tui entry shows each recall as a fold row in the terminal TUI. The row sits in the session view, above the prompt box. Tested on OpenCode 2.2.5.

A collapsed row looks like this:

▸ ● memory [mode=search, query="how did we handle om-pi-todo", limit=3]
  • mode=search is the recall for your prompt. The query is cut to 60 characters.
  • mode=opening is the opening search on the first message of a new session, when openingContext is on. Its row shows the configured query.
  • mode=restore is the restore after a compaction or a resume. The row has no query.
  • limit is the number of memories OMMS added.
  • Click the row, or run the /omms-recall slash command, to unfold it. The row then lists the mode, the query (up to 300 characters), the limit, and each memory with its relevance, its id and a one-line headline.
  • /omms-recall unfolds all rows in view. If every row is already unfolded, it folds them all. It is also in the command palette. The ./tui entry registers it from an app-level slot, so it stays available for the whole TUI run, also when no session is on screen.
  • The TUI shows the latest 5 rows of the session in view. OMMS remembers which rows you unfolded.
  • A prompt with no matching memories adds no row.

The rows are on your screen only.

  • They read the recall that OMMS already made. They run no second search.
  • They add no message to the session transcript.
  • They do not change what the model sees.

To turn the rows off, set visibleRecall to false. A project config can turn them off but never on. See Configuration: Visible recall. OMMS still records the summaries when the setting is off.

How it works:

  1. The V2 server entry builds a short summary of each recall. The shared builder is src/core/recall-summary.ts.
  2. The server keeps the latest 20 summaries for each session in memory, and serves them over plugin RPC (list). It also sends a recalled message as a hint to refresh.
  3. The ./tui entry asks for the summaries and draws them with the session.composer.top slot. It registers /omms-recall with a second claim on the app slot. It treats recalled as a hint only, so rows still appear when the push does not arrive.
  4. If the RPC handler is missing or a draw call fails, the TUI shows no rows. The footer and OpenCode keep working.

Limits:

  • OpenChamber and other frontends that do not load the OpenCode TUI entry show nothing new. Their recall stays as before.
  • OpenCode draws mode=search, mode=opening and mode=restore rows.
  • The server keeps summaries in memory only. They are not stored on disk. They are lost when OpenCode restarts.
  • Subagent sessions do not show rows. OMMS records no summary for a session that has a parent session, whatever visibleRecall says.
  • The rows and /omms-recall exist in the OpenCode terminal TUI and in the interactive terminal of Pi. Claude Code draws its own recall rows from a separate module (hooks/omms-recall.jsx) and has no such slash command. See Using memory: Host differences.

Capture boundary

Each user prompt is one work unit: the prompt plus the assistant messages up to the next user prompt.

  • From assistant messages, capture takes visible text, and tool names with their inputs.
  • It leaves out reasoning and tool outputs. It cuts tool inputs to 100 characters.
  • The plugin claims a prompt before capture. So repeated idle events or several windows never capture it twice.
  • A failed capture tries again up to autoCaptureMaxRetries times (default 3), 2 and 4 seconds apart. If the last try fails because the model cannot be reached, the turn goes to the capture retry queue.

Injection with the first message, subagents and restore

OpenCode V2 adds only the recall for the current prompt by default. Two options change this. See Configuration: Memory injection.

  • With openingContext on, the first message of a new session also gets the memories that match openingContextQuery. OpenCode V2 has no model request before the first prompt, so the opening section goes with that message.
  • Child sessions (subagents) get the prompt recall when subagentMemory is on (the default). A child gets no opening section and no restore after a resume.

Compaction and resume

The plugin does not replace OpenCode's compaction. After compaction, it restores up to compaction.memoryLimit memories from that session:

It adds them to the system prompt of later turns.

OpenCode V2 also restores after a resume. OpenCode V2 has no resume event. OMMS finds a resumed session when the first prompt it sees in this process finds earlier user messages in the history. This also happens after an OpenCode restart. The full history stays, so the restore is a short reminder. compaction.enabled set to false turns off both restores.

Profile learning

OpenCode runs the same learning pass as Pi and Claude Code. See Using memory: User profile for the steps and the settings.

  • The pass starts after the idle capture, when capture is on.
  • It uses the model that the capture rule above chooses. An OpenCode model or the session's model answers through OpenCode structured output, with a time limit of 120 seconds for each call.
  • When the rule chooses the external API, the pass uses the external API.
  • When the OpenCode model fails and the external API is fully configured, the pass uses the external API. The terminal interface shows the toast Using fallback provider with "OpenCode model failed (); using configured fallback."
  • When the OpenCode model fails and the external API is not configured, the pass fails with the OpenCode error. The 10-minute wait starts.
  • With showUserProfileToasts on, a saved pass shows the toast User profile updated with "Analysed N prompts and updated your profile" in the terminal interface. Pi shows the same words.
  • The saved profile version has the history text OpenCode analysis of N prompts.

Automatic profile cleanup

After a profile learning pass takes the count of analysed prompts past a multiple of userProfileAutoCleanupInterval (default 500), the shared pass starts the automatic cleanup in the background. It uses the same model as profile learning and sends the profile in batches of up to 100 items. A run that is still going when OpenCode ends saves nothing. See Using memory: Automatic cleanup.

Provenance

Memories captured from OpenCode carry:

{
  "host": "opencode",
  "hostSessionId": "<opencode session id>",
  "sourceType": "live-capture",
  "promptId": "<user message id>",
  "sourceEntryIds": ["<assistant message ids>"],
  "sourceTimestamp": 1767225600000
}

Imported memories use sourceType: "history-import", plus sourceFile and importId. Provenance is only metadata. It never changes which memories either host can retrieve.

Shared-store expectations

OpenCode and Pi can run in separate processes against the same store.

  • Writes go through the same shard allocation and write-lock path.
  • The same project folder resolves to the same project tag from either host (omms_project_<hash>).
  • Rows that older versions wrote under opencode_ are migrated automatically on first start.

Limitations

  • Profile learning and daily maintenance run in every OpenCode process. Daily maintenance runs at most once a day in each process.
  • Manual history import covers the current project by default. See opencode-history-import.md.

Host parity

Pi, OpenCode V2 and Claude Code offer the same memory injection: the recall for each prompt, an optional opening context, subagent memory and a restore after compaction or resume. The differences that stay, with their reasons, are in Using memory: Host differences.

Pi and OpenCode offer the same user capabilities. Both hosts show the recall rows in their terminal UI, built by the shared builder in src/core/recall-summary.ts. See Pi adapter: Recall rows.