Documentation

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, the toolkit we use for typed SDK generation.

Install

npm install crosmos

pip install crosmos

Authenticate

Create an API key from Settings -> API Keys in the Crosmos Console. Keys use the csk_ prefix.

export CROSMOS_API_KEY="csk_..."

export CROSMOS_API_KEY="csk_..."

Create a client

import Crosmos from "crosmos";

const client = new Crosmos();

from crosmos import Crosmos

client = Crosmos()

from crosmos import AsyncCrosmos

client = AsyncCrosmos()

Create a memory space

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

const space = await client.spaces.create({
	name: "personal-agent",
	description: "Memory for the user's personal agent",
});

console.log(space.id);

space = client.spaces.create(
    name="personal-agent",
    description="Memory for the user's personal agent",
)

print(space.id)

space = await client.spaces.create(
    name="personal-agent",
    description="Memory for the user's personal agent",
)

print(space.id)

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

const spaces = await client.spaces.list({ name: "personal-agent" });
const space = spaces.spaces[0];

spaces = client.spaces.list(name="personal-agent")
space = spaces.spaces[0]

spaces = await client.spaces.list(name="personal-agent")
space = spaces.spaces[0]

Ingest content

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

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);

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)

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)

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

const job = await client.jobs.getStatus(ingest.job_id);

console.log(job.status);

job = client.jobs.get_status(ingest.job_id)

print(job.status)

job = await client.jobs.get_status(ingest.job_id)

print(job.status)

Ingest a conversation

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

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);

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)

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)

Search memories

Use hybrid search to retrieve relevant memories from a space.

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);
}

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)

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)

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

Advanced SDK usage

Configure retries, timeouts, errors, logging, raw responses, and runtime options.

MCP

Connect Crosmos to an AI client without writing application code.

Getting Started

Concepts

MCP

SDKs

SDKs

Install

Authenticate

Create a client

Create a memory space

Ingest content

Ingest a conversation

Search memories

Resources

Next steps

Advanced SDK usage

MCP

​Install

​Authenticate

​Create a client

​Create a memory space

​Ingest content

​Ingest a conversation

​Search memories

​Resources

​Next steps

Advanced SDK usage

MCP

Install

Authenticate

Create a client

Create a memory space

Ingest content

Ingest a conversation

Search memories

Resources

Next steps