Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crosmos.dev/llms.txt

Use this file to discover all available pages before exploring further.

Crosmos ships an MCP server that exposes the memory layer’s search, ingestion, and management tools over the Model Context Protocol. Any MCP-compatible client can store and retrieve memories without custom integrations. See the Quickstart for installation and client configuration.

​
Authenticate

Your API key can be stored in a credentials file or set as an environment variable. Generate one from Settings → API Keys in the Crosmos Console. Keys use the csk_ prefix. The server resolves credentials in this order:
  1. CROSMOS_API_KEY environment variable — overrides everything
  2. ~/.crosmos/credentials.json — created by auth login
  3. Error — no key found

​
Login

npx @crosmos/crosmos-mcp auth login
Prompts for your API key, validates it against the Crosmos API, and saves it to ~/.crosmos/credentials.json. The file is stored with restricted permissions (0600). To use a custom API base URL: 
npx @crosmos/crosmos-mcp auth login --base-url https://api.crosmos.dev

​
Check status

npx @crosmos/crosmos-mcp auth status

​
Logout

npx @crosmos/crosmos-mcp auth logout
Removes the stored credentials file.

​
CLI reference

npx @crosmos/crosmos-mcp                        # Start MCP server (stdio)
npx @crosmos/crosmos-mcp setup                   # Interactive setup (auth + client install + skill)
npx @crosmos/crosmos-mcp auth login              # Authenticate with API key
npx @crosmos/crosmos-mcp auth logout             # Remove stored credentials
npx @crosmos/crosmos-mcp auth status             # Show current auth state
npx @crosmos/crosmos-mcp skill install <client>  # Install the Crosmos skill
The skill install command accepts: opencode, cursor, claude-code, windsurf, vscode.

​
Skills

The Crosmos skill teaches your AI editor how to use memory tools effectively. It adds auto-intent rules so the agent automatically decides when to search or store memories without explicit prompts. 
npx @crosmos/crosmos-mcp skill install opencode
The skill is also installed during setup. Supported clients:
ClientSkill location
opencode~/.opencode/skills/crosmos/SKILL.md
Claude Code~/.claude/skills/crosmos/SKILL.md
Cursor~/.cursor/skills/crosmos/SKILL.md
Windsurf~/.windsurf/rules/SKILL.md
VS Code~/.vscode/skills/crosmos/SKILL.md

​
Environment variables

VariableDescriptionDefault
CROSMOS_API_KEYAPI key for authentication (overrides credentials file)—
CROSMOS_API_BASE_URLBase URL for the Crosmos Memory APIhttps://api.crosmos.dev
DEFAULT_SPACE_IDDefault memory space UUID (optional)—
DEFAULT_SPACE_NAMEDefault memory space name; resolved via /spaces?name=. Ignored if DEFAULT_SPACE_ID is set.—
CROSMOS_API_TIMEOUTRequest timeout in milliseconds30000

​
Tools

​
search_memories

Retrieve relevant memories using hybrid retrieval.
​
string
required
The search query text.
{
  "query": "What programming languages does the user prefer?",
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
The server combines semantic (vector), keyword (full-text), and graph-based retrieval and returns ranked results with scores and memory types.

​
add_memory

Store new content into a memory space. Content is processed through an extraction pipeline that identifies entities, relationships, and creates structured knowledge graph entries.
Provide exactly one of sources or messages. They are mutually exclusive.
Store a text memory: 
{
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sources": [
    {
      "content": "User switched from Google to Anthropic. Prefers Rust for systems work.",
      "content_type": "text"
    }
  ]
}
Ingest a conversation: 
{
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "messages": {
    "messages": [
      { "role": "user", "content": "I just moved to Austin for a new startup job" },
      { "role": "assistant", "content": "Congratulations on the move!" }
    ],
    "session_id": "conv_001",
    "session_date": "2025-06-15"
  }
}

​
list_spaces

List all memory spaces owned by the authenticated user. Call this to discover available space IDs needed by search_memories and add_memory. No parameters required.

​
health_check

Check the connectivity and status of the Crosmos Memory Layer API. No parameters required.

​
How agents use it

When an agent receives a user message, it calls search_memories to fetch relevant context. After responding, it calls add_memory to store the new exchange. The next conversation starts with everything the agent already knows. The server automatically resolves a default space ID if you don’t specify one. If no spaces exist, the agent prompts you to create one from the Crosmos dashboard.

​
Next steps

How it works

Understand the knowledge graph behind the API.

Memories

Learn how Crosmos structures and retrieves context.