Skip to main content
The Crosmos Claude Code plugin adds project memory to Claude Code. It recalls relevant context when a session starts, captures your conversations automatically through lifecycle hooks, and adds /crosmos-recall and /crosmos-save skills for on-demand lookups and explicit notes. Use this plugin when you want Claude Code to remember project decisions, preferences, and prior work without managing memory by hand. If you only need callable memory tools, use MCP instead.

​
Prerequisites

  • Claude Code
  • Node.js 18 or later
  • A Crosmos API key from the Crosmos Console
  • At least one Crosmos memory space
Keys use the csk_ prefix.

​
Install

Run these inside Claude Code:
The plugin ships as a single bundled script, so there is nothing to install on your machine and no node_modules to manage.

​
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. Set it up in your terminal, not in the Claude session:
You can also grab a key from the Crosmos Console and either drop it in ~/.crosmos/credentials.json or export CROSMOS_API_KEY. Your key is entered in the terminal, never in the Claude conversation.

​
Verify

The status command reports your API key status, the resolved memory space, and connectivity.

​
How it works

Two lifecycle hooks run a single bundled script on Claude Code events. Everything runs in-process through the crosmos SDK, secrets never leave your machine, and the hooks fail open, so memory being unavailable never blocks your session. Two skills let you reach memory directly:
  • /crosmos-recall — ask Claude to look something up on demand.
  • /crosmos-save — ask Claude to save a specific note when you want to be explicit.
Recall runs automatically on session start and capture runs on every turn, so these skills are only for when you want manual control.

​
Configuration

Configure the plugin with environment variables. If neither CROSMOS_SPACE_ID nor CROSMOS_SPACE_NAME is set, the plugin uses the first available memory space.

​
Troubleshooting

​
Recall or capture is not running

Check your status:
It reports whether an API key is found, which space resolved, and whether the API is reachable.

​
No API key is configured

Set CROSMOS_API_KEY or run setup in your terminal:

​
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.

​
Debug hook behavior

Enable debug logging:
Logs are written to <tmp>/crosmos-claude.log.

​
Uninstall

Open the plugin manager in Claude Code and remove the crosmos plugin:
Existing memories in Crosmos are preserved.

​
Next steps

MCP

Connect Crosmos memory tools to AI clients.

Memory tools

See the callable memory tool schemas.