Skip to main content
The Crosmos opencode plugin adds project memory to opencode. 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 through the crosmos_recall and crosmos_save tools. The plugin makes no model calls of its own, so it behaves the same whichever provider or model you run. Use it when you want opencode to remember project decisions, preferences, and prior work without managing memory by hand. If you only need callable memory tools, use MCP instead.

​
Prerequisites

  • opencode, which runs plugins on the Bun runtime it ships with
  • A Crosmos API key from the Crosmos Console
  • At least one Crosmos memory space
Keys use the csk_ prefix.

​
Install

The CLI registers the plugin in your opencode config and saves your key:
To wire it up by hand, add the plugin to ~/.config/opencode/opencode.json (or a project opencode.json):
To pass options inline instead of using the environment or credentials file, use the tuple form:
Before an npm publish you can install straight from GitHub, which opencode builds on install, with "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 API key from ~/.crosmos/credentials.json — the same file the Crosmos CLI and Console use, so if you have set up Crosmos anywhere it works without extra steps. The quickest way to create it:
You can also grab a key from the Crosmos Console 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.

​
Verify

The status command prints connectivity and the resolved memory space.

​
How it works

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 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. Because recall runs as a visible crosmos_recall tool step rather than a blocking hook, your first message never waits on memory. The agent loads your project’s profile — conventions, decisions, and coding preferences — at the start of a session, recalls again whenever a request depends on past context, and records durable, user-specific facts with crosmos_save as they surface.

​
CLI commands

​
Configuration

Each value resolves from opencode plugin options first, then the environment, then the credentials file. All are optional except the API key. If neither spaceId nor spaceName is set, the org’s first space is used.

​
Privacy

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

​
Troubleshooting

​
Memory is not working

Check connectivity and the resolved space:

​
No API key is configured

Without a key the plugin is a silent no-op. Save one or export CROSMOS_API_KEY:

​
No memory space is available

Create a memory space in the Crosmos Console. You can pin a specific space with CROSMOS_SPACE_ID or CROSMOS_SPACE_NAME, or the spaceId / spaceName plugin options.

​
Uninstall

Add --project to remove it from a project config. Existing memories in Crosmos are preserved.

​
Next steps

MCP

Connect Crosmos memory tools to AI clients.

Memory tools

See the callable memory tool schemas.