Skip to main content
The Crosmos MCP server exposes four 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.
​
string
required
The search query.
{
  "query": "What editor does the user prefer?",
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
The tool returns a ranked text response 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.

​
Raw source

{
  "space_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sources": [
    {
      "content": "User prefers detailed technical explanations and uses Neovim.",
      "content_type": "text",
      "meta": {
        "source": "agent-session"
      }
    }
  ]
}
Source fields:
FieldTypeDefaultDescription
contentstringrequiredRaw content text.
content_typestringtextContent type such as text or markdown.
rolestringnullSpeaker role for conversation-like content.
sequencenumber0Order within a batch.
metaobjectnullArbitrary metadata.

​
Conversation

{
  "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",
    "meta": {
      "app": "agent"
    }
  }
}
Conversation fields:
FieldTypeDefaultDescription
messagesarrayrequiredOrdered { role, content } messages.
session_idstringnullConversation identifier.
session_datestringnullISO datetime for the session.
metaobjectnullMetadata attached to created sources.

​
list_spaces

List spaces available to the authenticated user. 
{}
Agents should call this when they need to discover a space ID or when default space resolution fails.

​
health_check

Check connectivity to the Crosmos Memory API. 
{}
The tool returns the API health status.

​
Agent usage pattern

1

Search before answering

Use search_memories when the user asks about prior context, preferences, or history.
2

Answer with context

Use returned memories as grounded context, not as the final answer by themselves.
3

Store new context

Use add_memory when the user shares facts, preferences, corrections, or conversation context worth remembering.