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

# Tools

> MCP tool schemas and examples for Crosmos memory.

The Crosmos MCP server exposes four callable tools. Memory tools accept an optional `space_id`; when omitted, the server resolves a default space from configuration or the authenticated account.

## `search_memories`

Search memories with hybrid retrieval.

<ParamField query="string" required>
  The search query.
</ParamField>

<ParamField space_id="string">
  Memory space UUID. If omitted, the server resolves a default space.
</ParamField>

```json theme={null}
{
  "query": "What editor does the user prefer?",
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

The tool returns ranked text results with score, memory type, optional event time, and memory content.

## `add_memory`

Store raw sources or a conversation. Provide exactly one of `sources` or `messages`.

<ParamField space_id="string">
  Memory space UUID. If omitted, the server resolves a default space.
</ParamField>

<ParamField sources="array">
  Raw content sources to ingest.
</ParamField>

<ParamField messages="object">
  Conversation messages to ingest through the conversations endpoint.
</ParamField>

### Raw source

```json theme={null}
{
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sources": [
    {
      "content": "User prefers detailed technical explanations and uses Neovim.",
      "content_type": "text",
      "visibility": "private",
      "meta": {
        "source": "agent-session"
      }
    }
  ]
}
```

Source fields:

| Field | Type | Default | Description |
| - | - | - | - |
| `content` | string | required | Raw content text. |
| `content_type` | string | `text` | Content type such as `text` or `markdown`. |
| `role` | string | `null` | Speaker role for conversation-like content. |
| `visibility` | string | `private` | `private` or `org`. Organization-visible memories can be read by authorized organization members. |
| `meta` | object | `null` | Arbitrary metadata. |

### Conversation

```json theme={null}
{
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "messages": {
    "messages": [
      { "role": "user", "content": "I moved my backend to Bun." },
      { "role": "assistant", "content": "I'll remember that for future setup." }
    ],
    "session_id": "setup-chat-001",
    "session_date": "2026-05-28T10:00:00Z",
    "visibility": "private"
  }
}
```

Conversation fields:

| Field | Type | Default | Description |
| - | - | - | - |
| `messages` | array | required | Ordered `{ role, content }` messages. |
| `session_id` | string | `null` | Conversation identifier. |
| `session_date` | string | `null` | ISO datetime for the conversation reference time. |
| `visibility` | string | `private` | `private` or `org`. Organization-visible memories can be read by authorized organization members. |

## `list_spaces`

List spaces available to the authenticated user.

```json theme={null}
{}
```

Call this when you need to discover a space ID or when default space resolution fails.

## `health_check`

Check connectivity to the Crosmos Memory API.

```json theme={null}
{}
```

The tool returns the API health status.

## Agent usage pattern

<Steps>
  <Step title="Search before answering">
    Use `search_memories` when the user asks about prior context, preferences, or history.
  </Step>

  <Step title="Answer with context">
    Use returned memories as grounded context, not as the final answer by themselves.
  </Step>

  <Step title="Store new context">
    Use `add_memory` when the user shares facts, preferences, corrections, or conversation context worth remembering.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.