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
pluginslist). The package loads under OpenCode V2 only. See ADR-048. - The plugin id is always
omms, whatever the npm package name.
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.
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.jsononly. It never creates the file. OpenCode createscli.json, and when the file is absent the first start of OpenCode V2 moves oldtui.jsonsettings into it. A file that OMMS made would stop that move. If the file is missing, start OpenCode once and runsetupagain. Do not create the file by hand. - It adds the string
om-memory-systemat the end ofplugins, or adds apluginskey 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
setupran is kept. A file that already has the entry by then is left alone. - When
cli.jsonis 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-systemin any form, for exampleom-memory-system@6.4.0. - It changes nothing when the file is not valid JSON or when
pluginsis 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):
- Build and pack the plugin with the command below.
- Install the tarball the same way OpenCode installs a published package.
bun install && bun run build && npm packscripts/verify-nested-onnxruntime-fixture.mjs shows the install layout that
CI checks for a packed build.
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
memorytool before it debugs or investigates, and when you refer to earlier work. Thememorytool description gives the same instruction.
See Using memory: The omms-memory 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
memorisemode of thememorytool and reports thems-ID. OpenCode passes its session ID to the tool, so a repeat snapshot can replace the earlier one whenmemorisationRepeatisreplace.
See Using memory: The omms-remember skill.
- Run
opencode plugin remove om-memory-system. With OpenCode 2.2.6 it removes the entry fromopencode.jsonand fromcli.json. Opencli.jsonand remove the entry by hand if it is still there. - Stop the login item. OpenCode starts the web app at sign-in while
webServerAutoStartistrue, and each OpenCode start installs the item again. Set"webServerAutoStart": falsein~/.config/omms/omms.jsonc, then runnpx om-memory-system@latest web uninstall. The command also sets that value and removes the item. - Restart OpenCode and run
opencode service restart.
Your memories stay in ~/.omms/data. Delete that folder only when you want to lose them.
The plugin reads the same configuration files as the Pi extension:
~/.config/omms/omms.jsonc(global). If this file does not exist, the plugin reads the legacy~/.config/opencode/opencode-mem.jsonc.<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.
storagePathdefaults to~/.omms/data. So both hosts use the same store for the same project, unless you change it.
OpenCode-specific options:
The plugin chooses the capture model with the same rule as Pi (see Configuration: Choosing the model):
opencodeProvider/opencodeModel, if set.- The external API (
memoryModel/memoryApiUrl/memoryApiKey), if configured. - 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.
| 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. |
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: trueto the global config file. The default is off. - An older config file with
"autoCleanupEnabled": truedeletes nothing. See Configuration: Memory cleanup.
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.
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 setwebServerPortin 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.
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, thenomms: ✔when the web app answers onwebServerPort.omms: ✘ web app offwhen the web app does not answer. Capture and retrieval keep working.omms: ✘when the footer cannot start its status check.· <version> availablewhen 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, restartafter OMMS installs the newer release in the background and finds the new version on disk. A toast tells you to restart OpenCode and runopencode 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 oropencode 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> availableand 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.
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=searchis the recall for your prompt. The query is cut to 60 characters.mode=openingis the opening search on the first message of a new session, whenopeningContextis on. Its row shows the configured query.mode=restoreis the restore after a compaction or a resume. The row has no query.limitis the number of memories OMMS added.- Click the row, or run the
/omms-recallslash 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-recallunfolds all rows in view. If every row is already unfolded, it folds them all. It is also in the command palette. The./tuientry 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:
- The V2 server entry builds a short summary of each recall. The shared builder is
src/core/recall-summary.ts. - The server keeps the latest 20 summaries for each session in memory, and serves them over plugin RPC (
list). It also sends arecalledmessage as a hint to refresh. - The
./tuientry asks for the summaries and draws them with thesession.composer.topslot. It registers/omms-recallwith a second claim on theappslot. It treatsrecalledas a hint only, so rows still appear when the push does not arrive. - 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=openingandmode=restorerows. - 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
visibleRecallsays. - The rows and
/omms-recallexist 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.
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
autoCaptureMaxRetriestimes (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.
OpenCode V2 adds only the recall for the current prompt by default. Two options change this. See Configuration: Memory injection.
- With
openingContexton, the first message of a new session also gets the memories that matchopeningContextQuery. 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
subagentMemoryis on (the default). A child gets no opening section and no restore after a 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.
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
showUserProfileToastson, 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.
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.
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.
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.
- 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.
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.
{ // 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", }