Agentmemory Launcher for OpenCode

OpenCode plugin that auto-starts the agentmemory backend with health-check supervision.

English | 中文 | Français

Requirements

• OpenCode V2 (opencode2)
• Node.js ≥ 18.0.0 for the plugin itself; the agentmemory 0.9.30 backend requires Node.js ≥ 20.0.0
• agentmemory backend (auto-installed via npx @agentmemory/agentmemory if not present)

V1 users: OpenCode V1 (opencode 1.x) is no longer supported as of v4.0.0 — pin opencode-agentmemory-launcher@^3 if you still need V1.

Note: This plugin has only been tested on Windows 11. If you need support for other platforms, pull requests are welcome.

What It Does

This plugin automatically starts the agentmemory backend (REST API + iii-engine) when OpenCode loads its configuration. It runs once per OpenCode process and health-checks the backend every 60 seconds, restarting it if the process dies.

Compatibility

Built for agentmemory 0.9.30 (2026-10-06) and backward compatible with earlier releases:

• Auth is on by default. agentmemory generates a secret into ~/.agentmemory/secret on first start. The launcher only calls the always-public /agentmemory/livez, so it needs no secret and is unaffected. Hand-written REST calls to :3111 now need Authorization: Bearer $(cat ~/.agentmemory/secret).
• iii-engine 0.22.1. agentmemory 0.9.30 moved its engine pin from 0.11.2 to 0.22.1 and enforces it. The launcher does not manage the engine (the agentmemory CLI does), but a mismatched pin now exits the CLI with code 1 — the launcher surfaces that as a warn.
• Newest version wins. On Windows the launcher starts the newest agentmemory it can find in the npx cache or a global install on PATH, so npm i -g @agentmemory/agentmemory@latest takes effect without clearing the npx cache.

Installation

From npm (recommended)

Add to your OpenCode config (plugins, plural):

{
  "plugins": ["opencode-agentmemory-launcher@latest"]
}

OpenCode will automatically install the package at startup. See the V2 plugins guide for more details.

From local file

Place the plugin file in .opencode/plugins/:

.opencode/plugins/
└── agentmemory-launcher.ts

Files in this directory are automatically loaded at startup.

Manual Installation (from GitHub Releases)

1. Download agentmemory-launcher.ts from the latest GitHub Release
2. Place it in .opencode/plugins/:

.opencode/plugins/
└── agentmemory-launcher.ts

OpenCode loads .ts files from .opencode/plugins/ automatically at startup.

Usage

This launcher starts the agentmemory backend. To use agentmemory with OpenCode, also install the agentmemory plugin and refer to the OpenCode agentmemory plugin usage guide for setup instructions, available tools, and configuration options.

Updating

To update agentmemory to the latest version:

npx @agentmemory/agentmemory upgrade

If you installed agentmemory globally, update that copy instead with npm i -g @agentmemory/agentmemory@latest — the launcher picks the newest version across the npx cache and global installs.

After updating, stop the running agentmemory process and clear the npx cache:

Windows (PowerShell):

# Stop the agentmemory process
Get-Process -Name "node" | Where-Object {
    (Get-CimInstance Win32_Process -Filter "ProcessId = $($_.Id)").CommandLine -match 'agentmemory'
} | Stop-Process -Force

# Clear the npx cache
Get-ChildItem "$env:LOCALAPPDATA\npm-cache\_npx" -Directory | Where-Object {
    Test-Path "$($_.FullName)\node_modules\@agentmemory"
} | Remove-Item -Recurse -Force

Restart OpenCode to relaunch agentmemory with the updated version.

How It Works

1. On load (setup()): the plugin starts a health-check interval (60s)
2. Health check: Pings GET /agentmemory/livez on the backend (always public, no auth — even with agentmemory 0.9.30's auth-by-default)
3. Auto-restart (two-mode): If the health check fails, the backend is launched.
   • Startup (backend down when the plugin loads): opens a visible Windows Terminal tab titled agentmemory (wt -w 0 nt --title agentmemory --suppressApplicationTitle node <cli>) — Windows Terminal launches node itself, so no cmd/pwsh shell is involved. The backend coming up is visible; focus is taken once here — acceptable at startup, and never on the recovery path. Falls back to the silent path when wt.exe is unavailable.
   • Recovery (every later (re)launch from the 60s loop): fully silent. On Windows the plugin bypasses npx/cmd entirely — it resolves the newest dist/cli.mjs it can find in the npm/npx cache or a global install on PATH, and spawns node directly on it, so the process tree (node → cli.mjs → iii.exe) never touches cmd.exe and never allocates a console: no window/tab and no focus steal, mid-session or while idle (plain windowsHide is insufficient because every cmd.exe hop lets a grandchild allocate a new console). Falls back to an npx spawn when no local copy is found. Relaunches are throttled by a 90s boot grace window plus a cross-instance launch lock (multiple OpenCode servers share one backend)
4. Debug mode: Set OPENCODE_AGENTMEMORY_DEBUG=1 for verbose logging
5. Failure diagnostics: A backend launch that exits with a non-zero code is logged at warn with the likely causes — a daemon already answering on the port (agentmemory 0.9.30 refuses to start a second instance) or the enforced iii-engine pin mismatch. A visible startup tab whose process exits with a non-zero code stays open (Windows Terminal's closeOnExit: graceful) so the error text remains readable

Environment Variables

Variable	Default	Description
AGENTMEMORY_URL	http://localhost:3111	Backend API URL
OPENCODE_AGENTMEMORY_DEBUG	unset	Set to 1 for debug logging

Troubleshooting

The backend never comes up and the log shows a non-zero launch exit. Two common causes: agentmemory 0.9.30 enforces its iii-engine pin (v0.22.1), so a different engine on PATH makes the CLI exit with code 1; or a stale instance still owns the port. Run it manually to see the actual error:

npx @agentmemory/agentmemory doctor

A visible startup tab shows agentmemory worker did not become ready within 15s and exits with code 1. A stale instance from an earlier session is still holding the REST port, so the fresh CLI starts its engine but its worker registration never becomes ready — a healthy fresh start completes in ~2s. Diagnose and restart the whole chain (never kill a single worker process: it may be the active route handler, and killing it makes /agentmemory/livez return 404):

Get-NetTCPConnection -LocalPort 3111 -State Listen   # who owns the port
npx @agentmemory/agentmemory stop                     # stop the instance it belongs to
# if that leaves the port held, stop the engine + worker pair together and
# let the launcher's supervision loop relaunch them (~60s, silently)

A newer agentmemory is installed but the launcher keeps running an older one. The launcher prefers the newest version across the npx cache and global installs; if a stale copy still wins, clear the cache:

npx clear-npx-cache

API

The plugin targets the OpenCode V2 plugin API (@opencode/plugin >= 2.0.18). Supervision starts in setup() when the plugin loads, and the returned cleanup function stops the health-check loop on unload.

import type { Plugin } from "@opencode/plugin";

const plugin: Plugin = {
  id: "agentmemory-launcher",
  setup: async (ctx) => {
    // start supervision; return cleanup
  },
};

export default plugin;

Development

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build
npm run build

# Run tests
npm test

Community

• Contributing Guide
• Code of Conduct
• Security Policy

License

GNU Affero General Public License v3.0

Copyright

Copyright (C) 2026 Cle2ment.