@crosmos/opencode

You don't manage memory. You use opencode normally — at the start of a session the agent loads your project's stored context, your conversations are saved automatically, and it recalls and saves durable facts proactively as it works. Nothing to remember, nothing to type, and your first message never waits on memory. It works the same whichever provider or model you're on, because the plugin makes no model calls of its own.

Requirements

• opencode (it runs plugins on Bun, which it already ships with).
• A crosmos api key (csk_…) from console.crosmos.dev.

Install

The CLI registers the plugin in your opencode config and saves your key:

bunx @crosmos/opencode install         # add "@crosmos/opencode" to your opencode config
bunx @crosmos/opencode set-key csk_…   # save the key to ~/.crosmos/credentials.json
bunx @crosmos/opencode status          # verify connectivity and resolved space

Or wire it up by hand — add to ~/.config/opencode/opencode.json (or a project opencode.json):

{
  "plugin": ["@crosmos/opencode"]
}

To pass options inline instead of env/credentials, use the tuple form:

{
  "plugin": [["@crosmos/opencode", { "spaceName": "my-project" }]]
}

Other sources. Before an npm publish, install straight from GitHub (opencode builds it on install): "plugin": ["github:crosmos-labs/opencode-crosmos"]. For local development, run bun run build and point at the built file: "plugin": ["file:///abs/path/opencode-crosmos/dist/index.js"].

Authentication

The plugin reads your crosmos key from ~/.crosmos/credentials.json — the same file the crosmos CLI and console use, so if you've set up crosmos anywhere, it just works. The quickest way to create it:

bunx @crosmos/opencode set-key csk_… --base-url https://api.crosmos.dev

Or grab a key from console.crosmos.dev and either drop it in ~/.crosmos/credentials.json or export CROSMOS_API_KEY. Without a key the plugin is a silent no-op, so opencode is never affected.

How it works

No magic. The plugin is a single in-process module that uses three opencode hooks and talks to crosmos over the crosmos sdk. Fact extraction and retrieval happen server-side, so the plugin itself makes no model calls and behaves identically across providers. Everything fails open — memory being unavailable never blocks your session, and secrets never leave your machine.

| hook | runs on | does | | --- | --- | --- | | chat.message | the first message of a session | injects a one-time, non-blocking directive telling the agent to load the project's memory | | event → session.idle | the session goes idle | captures new conversation turns and saves them | | tool → crosmos_recall / crosmos_save | when the agent decides it needs memory | recalls context, or saves a durable fact — proactively, without being asked |

• Recall — at the start of a session the agent loads your project's profile (conventions, decisions, coding preferences) by calling crosmos_recall, and recalls again on its own whenever a request depends on past context. It runs as a visible tool step, so your first message never waits on memory.
• Capture — as a session progresses, new turns are saved to crosmos automatically, secret-redacted and deduped per turn.
• Proactive save — the agent records durable, user-specific facts (preferences, decisions, conventions, corrections) with crosmos_save as they surface — not just when you ask.

CLI commands

crosmos-opencode install [--project]                  # add the plugin to the global (or project) config
crosmos-opencode uninstall [--project]                # remove it again
crosmos-opencode set-key <csk_…> [--base-url <url>]   # save the api key to ~/.crosmos/credentials.json
crosmos-opencode status                               # show connectivity and the resolved space

Configuration

Each value resolves from opencode plugin options first, then the environment, then the credentials file. All are optional except the api key.

| option | env | purpose | | --- | --- | --- | | apiKey | CROSMOS_API_KEY | api key (csk_…) | | baseUrl | CROSMOS_API_BASE_URL | api base url (default https://api.crosmos.dev) | | spaceId | CROSMOS_SPACE_ID | pin a memory space by id | | spaceName | CROSMOS_SPACE_NAME | resolve a memory space by name |

If neither spaceId nor spaceName is set, the org's first space is used.

Privacy

• All ingested content is scanned and secrets (keys, tokens, passwords) are masked before upload.
• Wrap anything you never want captured in <private>…</private> — those spans are stripped entirely.

Development

bun install
bun run build      # bun build → dist/index.js + dist/cli.js
bun run typecheck  # tsc --noEmit
bun run lint       # biome check
bun run format     # biome check --write

The plugin entry (dist/index.js) loads inside opencode; the CLI (dist/cli.js) is the crosmos-opencode bin. Both are compiled with bun build and published in dist.

License

MIT.