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: 
/plugin marketplace add crosmos-labs/claudecode-crosmos
/plugin install crosmos
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: 
npx @crosmos/crosmos-mcp setup
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

/crosmos:status
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.
HookWhen it runsWhat it does
SessionStartA session starts or resumesRecalls the most relevant memories for your project and injects them silently.
StopAt the end of each turnCaptures new conversation turns and saves them.
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.
Environment variablePurpose
CROSMOS_API_KEYAPI key. Overrides the credentials file.
CROSMOS_API_BASE_URLAPI base URL. Defaults to https://api.crosmos.dev.
CROSMOS_SPACE_IDPin a memory space by ID.
CROSMOS_SPACE_NAMEResolve and pin a memory space by name.
CROSMOS_DEBUGWrite a debug log to <tmp>/crosmos-claude.log.
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: 
/crosmos: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: 
export CROSMOS_API_KEY="csk_..."
npx @crosmos/crosmos-mcp setup

​
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: 
export CROSMOS_DEBUG=1
Logs are written to <tmp>/crosmos-claude.log.

​
Uninstall

Open the plugin manager in Claude Code and remove the crosmos plugin: 
/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.