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

# SDKs

> Build Crosmos memory into your application with official SDKs.

Use the official SDKs when you want Crosmos memory inside an application, service, worker, or custom agent runtime. The TypeScript and Python SDKs are generated from the Crosmos OpenAPI specification and expose typed access to the Memory API.

Crosmos also maintains [Ironic](https://github.com/crosmos-labs/ironic), the toolkit we use for typed SDK generation.

## Install

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install crosmos
  ```

  ```bash Python theme={null}
  pip install crosmos
  ```
</CodeGroup>

## Authenticate

Create an API key from **Settings -> API Keys** in the [Crosmos Console](https://console.crosmos.dev). Keys use the `csk_` prefix.

<CodeGroup>
  ```bash TypeScript theme={null}
  export CROSMOS_API_KEY="csk_..."
  ```

  ```bash Python theme={null}
  export CROSMOS_API_KEY="csk_..."
  ```
</CodeGroup>

## Create a client

<CodeGroup>
  ```ts TypeScript theme={null}
  import Crosmos from "crosmos";

  const client = new Crosmos();
  ```

  ```python Python (Sync) theme={null}
  from crosmos import Crosmos

  client = Crosmos()
  ```

  ```python Python (Async) theme={null}
  from crosmos import AsyncCrosmos

  client = AsyncCrosmos()
  ```
</CodeGroup>

## Create a memory space

Spaces isolate memories for a user, tenant, project, or agent.

<CodeGroup>
  ```ts TypeScript theme={null}
  const space = await client.spaces.create({
  	name: "personal-agent",
  	description: "Memory for the user's personal agent",
  });

  console.log(space.id);
  ```

  ```python Python (Sync) theme={null}
  space = client.spaces.create(
      name="personal-agent",
      description="Memory for the user's personal agent",
  )

  print(space.id)
  ```

  ```python Python (Async) theme={null}
  space = await client.spaces.create(
      name="personal-agent",
      description="Memory for the user's personal agent",
  )

  print(space.id)
  ```
</CodeGroup>

If you already know the space name, resolve it before making calls:

<CodeGroup>
  ```ts TypeScript theme={null}
  const spaces = await client.spaces.list({ name: "personal-agent" });
  const space = spaces.spaces[0];
  ```

  ```python Python (Sync) theme={null}
  spaces = client.spaces.list(name="personal-agent")
  space = spaces.spaces[0]
  ```

  ```python Python (Async) theme={null}
  spaces = await client.spaces.list(name="personal-agent")
  space = spaces.spaces[0]
  ```
</CodeGroup>

## Ingest content

Use source ingestion for raw text, markdown, or other source payloads.

<CodeGroup>
  ```ts TypeScript theme={null}
  const ingest = await client.sources.ingest({
  	space_id: space.id,
  	sources: [
  		{
  			content: "User prefers detailed technical explanations and uses Neovim.",
  			content_type: "text",
  			meta: {
  				source: "profile-import",
  			},
  		},
  	],
  });

  console.log(ingest.job_id);
  ```

  ```python Python (Sync) theme={null}
  ingest = client.sources.ingest(
      space_id=space.id,
      sources=[
          {
              "content": "User prefers detailed technical explanations and uses Neovim.",
              "content_type": "text",
              "meta": {"source": "profile-import"},
          }
      ],
  )

  print(ingest.job_id)
  ```

  ```python Python (Async) theme={null}
  ingest = await client.sources.ingest(
      space_id=space.id,
      sources=[
          {
              "content": "User prefers detailed technical explanations and uses Neovim.",
              "content_type": "text",
              "meta": {"source": "profile-import"},
          }
      ],
  )

  print(ingest.job_id)
  ```
</CodeGroup>

Crosmos processes ingestion asynchronously. Poll the job when your app needs to wait for extraction to finish:

<CodeGroup>
  ```ts TypeScript theme={null}
  const job = await client.jobs.getStatus(ingest.job_id);

  console.log(job.status);
  ```

  ```python Python (Sync) theme={null}
  job = client.jobs.get_status(ingest.job_id)

  print(job.status)
  ```

  ```python Python (Async) theme={null}
  job = await client.jobs.get_status(ingest.job_id)

  print(job.status)
  ```
</CodeGroup>

## Ingest a conversation

Use conversation ingestion for ordered chat history. Each message becomes a source with conversation provenance.

<CodeGroup>
  ```ts TypeScript theme={null}
  const conversation = await client.conversations.ingest({
  	space_id: space.id,
  	session_id: "chat-001",
  	session_date: "2026-05-28T10:00:00Z",
  	messages: [
  		{
  			role: "user",
  			content: "I want my agent to remember that I prefer Bun for TypeScript projects.",
  		},
  		{
  			role: "assistant",
  			content: "Got it. I will keep that in mind for future setup.",
  		},
  	],
  	meta: {
  		app: "example-agent",
  	},
  });

  console.log(conversation.source_ids);
  ```

  ```python Python (Sync) theme={null}
  conversation = client.conversations.ingest(
      space_id=space.id,
      session_id="chat-001",
      session_date="2026-05-28T10:00:00Z",
      messages=[
          {
              "role": "user",
              "content": "I want my agent to remember that I prefer Bun for TypeScript projects.",
          },
          {
              "role": "assistant",
              "content": "Got it. I will keep that in mind for future setup.",
          },
      ],
      meta={"app": "example-agent"},
  )

  print(conversation.source_ids)
  ```

  ```python Python (Async) theme={null}
  conversation = await client.conversations.ingest(
      space_id=space.id,
      session_id="chat-001",
      session_date="2026-05-28T10:00:00Z",
      messages=[
          {
              "role": "user",
              "content": "I want my agent to remember that I prefer Bun for TypeScript projects.",
          },
          {
              "role": "assistant",
              "content": "Got it. I will keep that in mind for future setup.",
          },
      ],
      meta={"app": "example-agent"},
  )

  print(conversation.source_ids)
  ```
</CodeGroup>

## Search memories

Use hybrid search to retrieve relevant memories from a space.

<CodeGroup>
  ```ts TypeScript theme={null}
  const search = await client.search.hybrid({
  	space_id: space.id,
  	query: "What does the user prefer for TypeScript projects?",
  	limit: 5,
  	include_source: true,
  });

  for (const candidate of search.candidates) {
  	console.log(candidate.content, candidate.score);
  }
  ```

  ```python Python (Sync) theme={null}
  search = client.search.hybrid(
      space_id=space.id,
      query="What does the user prefer for TypeScript projects?",
      limit=5,
      include_source=True,
  )

  for candidate in search.candidates:
      print(candidate.content, candidate.score)
  ```

  ```python Python (Async) theme={null}
  search = await client.search.hybrid(
      space_id=space.id,
      query="What does the user prefer for TypeScript projects?",
      limit=5,
      include_source=True,
  )

  for candidate in search.candidates:
      print(candidate.content, candidate.score)
  ```
</CodeGroup>

## Resources

| Resource        | Use it for                                               |
| --------------- | -------------------------------------------------------- |
| `spaces`        | Create, list, get, and delete spaces.                    |
| `sources`       | Ingest, list, get, and delete source documents.          |
| `conversations` | Ingest ordered message history.                          |
| `jobs`          | Poll ingestion jobs.                                     |
| `search`        | Retrieve relevant memories.                              |
| `memories`      | List, get, or soft-delete memories.                      |
| `entities`      | List entities and inspect recent memories for an entity. |
| `usage`         | Read usage and plan limits.                              |
| `health`        | Check API connectivity.                                  |

## Next steps

<CardGroup cols={2}>
  <Card title="Advanced SDK usage" icon="gear" href="/sdks/advanced">
    Configure retries, timeouts, errors, logging, raw responses, and runtime options.
  </Card>

  <Card title="MCP" icon="puzzle-piece" href="/mcp/overview">
    Connect Crosmos to an AI client without writing application code.
  </Card>
</CardGroup>