Cosmos

tu exocórtex de IA

Documentación

cosmos-mcp

Un exocórtex. Cada agente.
_{Servidor MCP para tu grafo de Cosmos.}

Cada IA que usas está construyendo su propio grafo privado de ti. Claude tiene uno. ChatGPT tiene uno. Cursor tiene uno. Ninguno de ellos se comunica entre sí, y ninguno es tuyo.

Cosmos invierte eso. Tu grafo de conocimiento vive en un solo lugar, y cualquier cliente compatible con MCP (Claude Code, Claude Desktop, Cursor, Codex, Zed, Continue) lee y escribe en el mismo. Cuando un agente nota algo duradero sobre ti, aterriza en el grafo. Cuando cambias de herramienta, el grafo te sigue. El usuario, no la plataforma, es dueño de la capa de integración.

Lo que llevas contigo es un archivo .polarity. Tuyo.

Instalación en una línea

curl -fsSL https://mcp.polarity-lab.com/install.sh | sh

En macOS, esto instala el servidor MCP, registra cosmos-mcp://, conecta Claude Desktop, Claude Code, Cursor, Codex, Zed y Continue, y luego instala Cosmos Sync.app para que iMessage, el historial del navegador, el calendario, las transcripciones de Claude Desktop y el historial de shell puedan sincronizarse en segundo plano. En Linux y Windows solo instala la ruta del servidor MCP.

Si quieres inspeccionar antes de cambiar algo:

curl -fsSL https://mcp.polarity-lab.com/install.sh -o install.sh
bash install.sh --dry-run
bash install.sh

Aprovisionamiento

Hay dos formas de obtener una clave pmk_… en tu Mac.

Automático. Inicia sesión en cosmos.polarity-lab.com/connectors, toca "abrir en cosmos-mcp". El sistema operativo abre un manejador de un solo uso que escribe la clave en tu llavero del sistema. Nunca ves la clave en bruto.

Para que ese enlace profundo funcione, registra el esquema de URL una vez:

npx -y @polarity-lab/cosmos-mcp install-handler

Esto coloca un pequeño .app en ~/Library/Application Support/cosmos-mcp/ y registra cosmos-mcp:// con Launch Services. Solo macOS.

Manual. Si ya tienes una clave pmk_…, o no quieres instalar el manejador:

npx -y @polarity-lab/cosmos-mcp provision pmk_xxx

El CLI valida la clave contra cosmos, luego la almacena en el llavero del sistema macOS bajo el servicio cosmos-mcp-key. Las llamadas posteriores a imessage sync, browser sync, calendar sync leen del llavero. No se necesita variable de entorno.

Confirmar acceso a iMessage.

npx -y @polarity-lab/cosmos-mcp imessage probe

Verifica que se haya otorgado Acceso completo al disco e informa cuántos chats son visibles. Si ves un mensaje EACCES, abre Configuración del Sistema, Privacidad y Seguridad, Acceso completo al disco, y agrega Terminal (o la aplicación que ejecute el CLI).

CI. Establece COSMOS_TOKEN=pmk_… en el entorno. Tiene prioridad sobre el llavero, por lo que los pipelines existentes siguen funcionando sin cambios.

Configuración manual de MCP

El instalador maneja esto para clientes comunes. Si quieres conectar un cliente manualmente, apúntalo al paquete.

npx -y @polarity-lab/cosmos-mcp init

Esto abre tu navegador. Inicia sesión en cosmos.polarity-lab.com, aprueba una clave por usuario, y el token se guarda en ~/.config/cosmos-mcp/token (0600). Luego apunta cualquier cliente MCP a él:

{
  "mcpServers": {
    "cosmos": {
      "command": "npx",
      "args": ["-y", "@polarity-lab/cosmos-mcp"]
    }
  }
}

Esa configuración se coloca en ~/Library/Application Support/Claude/claude_desktop_config.json para Claude Desktop, tu .cursor/mcp.json para Cursor, el equivalente para cualquier cliente.

Lo que obtienes

Once herramientas, cuatro de lectura, siete de escritura.

Lectura

Herramienta	Llamadas	Lo que devuelve
`polarity_whoami`	`GET /api/polarity/whoami`	Usuario vinculado + alcances. Sonda económica.
`polarity_export`	`POST /api/polarity/export`	Grafo personal completo como `polarity/v1` JSON.
`polarity_get_graph`	`GET /api/polarity`	Vista de grafo, limitada por entidad (`user`, `cosmos`, `polarity`).
`polarity_ask`	`POST /api/polarity/ask`	Pregunta en lenguaje natural sintetizada sobre el grafo.

Escritura

Herramienta	Llamadas	Lo que hace
`polarity_observe`	`POST /api/polarity/observe`	Observación libre. Cosmos extrae.
`polarity_record_event`	`POST /api/polarity/observe` (kind=event)	Algo sucedió en un punto en el tiempo.
`polarity_record_preference`	`POST /api/polarity/observe` (kind=preference)	Una regla de gusto, disgusto o estilo de trabajo.
`polarity_capture_turn`	`POST /api/polarity/capture-turn`	Entrega un intercambio completo de usuario/asistente a cosmos. Extrae todas las observaciones duraderas en una sola llamada. Prefiere esto sobre múltiples llamadas a `polarity_observe`.
`polarity_dump`	`POST /api/polarity/dump`	Mensaje corto anclado a una ubicación.
`polarity_checkin`	`POST /api/polarity/checkin`	Registro en un punto de referencia. Activa la detección de co-presencia.
`polarity_declare`	`POST /api/polarity/declare`	Declara presencia futura en un punto de referencia.

Fuentes

El servidor MCP es una forma de escribir en el grafo. Cosmos acepta páginas de origen desde cualquier lugar donde guardes notas, y las herramientas de lectura de MCP ven todo a través de la misma vista.

Fuente	Cómo se conecta	Qué se guarda
iMessage	CLI local: `npx -y @polarity-lab/cosmos-mcp imessage sync`. Solo Mac. Otorga a Terminal Acceso completo al disco primero.	Turnos conversacionales de `chat.db`, con contenido de texto. Las personas aparecen como nodos de persona en tu grafo, dimensionados por el peso de la conversación, nombrados a través de tu libreta de direcciones local, fechados por tus marcas de tiempo reales de mensajes.
Claude Desktop	CLI local: `npx -y @polarity-lab/cosmos-mcp claude-desktop sync`. Lee transcripciones de sesiones de Claude Code en `~/.claude/projects/`.	Cada sesión de Claude Code se convierte en un nodo de hilo; los turnos de usuario y asistente se guardan en `conversation_turns` con texto completo. El cableado de uso de herramientas se elimina en el lado del cliente.
Historial de shell	CLI local: `npx -y @polarity-lab/cosmos-mcp shell-history sync`. Lee `~/.zsh_history` (usa bash/fish como respaldo) con una marca de agua de desplazamiento de bytes.	Cada ventana de sincronización se guarda como un `source_page` con clave `shell-history:<sync-iso>`, cuerpo = comandos unidos por saltos de línea. Los comandos triviales (`ls`, `cd ..`, caracteres individuales) y los duplicados consecutivos se filtran en el lado del cliente.
Notion	OAuth en cosmos.polarity-lab.com/connectors. Elige las páginas y bases de datos que quieras compartir.	Cada página de Notion se convierte en un nodo `source_page`, con clave por id de Notion, mantenido actualizado con una sincronización diaria.
Obsidian	Plugin de la comunidad: polarity-lab/obsidian-cosmos. Pega tu clave `pmk_`, apunta a tu bóveda.	Cada nota se convierte en un nodo `source_page` con clave por ruta relativa a la bóveda. Las etiquetas y los wikilinks se resuelven en aristas.
Clientes MCP	Este paquete.	Observaciones, eventos, preferencias, volcados de ubicación, registros, declaraciones.
API directa	`POST /api/polarity/observe` con tu clave.	Cualquier cosa que puedas expresar como observación.

Las páginas sin cambios se omiten en el lado del servidor, por lo que volver a sincronizar una bóveda tranquila o un espacio de trabajo de Notion estable cuesta casi nada. La sincronización de iMessage también es incremental, con marca de agua en la última ejecución exitosa, por lo que volver a ejecutarla no hace nada hasta que lleguen nuevos mensajes.

Sincronización de iMessage

cosmos-mcp incluye un subcomando imessage que lee tu base de datos local de Mensajes y guarda cada conversación en tu grafo.

# default: incremental sync, 90-day window on first run
npx -y @polarity-lab/cosmos-mcp imessage sync

# re-sync the original 90-day window regardless of watermark
npx -y @polarity-lab/cosmos-mcp imessage sync --backfill

# pull everything since a specific date
npx -y @polarity-lab/cosmos-mcp imessage sync --since 2024-01-01

# check what the last run did
npx -y @polarity-lab/cosmos-mcp imessage status

Un filtro de basura de tres reglas (remitentes sin respuesta, números de código corto, contactos de bajo volumen) mantiene el grafo limpio. Tu libreta de direcciones resuelve números de teléfono y correos electrónicos en nombres de contacto reales. La lectura es local en tu Mac; solo los turnos extraídos y normalizados van a tu grafo de cosmos, que es tu cuenta.

Sincronización de Claude Desktop

cosmos-mcp incluye un subcomando claude-desktop que observa las transcripciones de sesiones de Claude Code y guarda cada turno en tu grafo. La superficie de chat de escritorio en sí almacena las conversaciones en el lado del servidor, por lo que la fuente en disco, viva y observable, es ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl.

# default: incremental, watermarked per session
npx -y @polarity-lab/cosmos-mcp claude-desktop sync

# limit to recent activity
npx -y @polarity-lab/cosmos-mcp claude-desktop sync --since 2026-05-01

# scan and report without shipping
npx -y @polarity-lab/cosmos-mcp claude-desktop sync --dry-run

# see what the last run did
npx -y @polarity-lab/cosmos-mcp claude-desktop status

Los bloques de uso de herramientas, el cableado de hooks y los turnos de sub-agentes (sidechain) se eliminan en el lado del cliente; solo se envía el texto visible que el usuario y el asistente intercambiaron. Cada id de sesión se convierte en su propio nodo de hilo, con clave por (user_id, "claude-desktop", session_id).

Sincronización en segundo plano (macOS)

cosmos-mcp daemon install coloca un LaunchAgent que se activa cada cuatro horas y ejecuta las sincronizaciones de navegador, iMessage, calendario, claude-desktop e historial de shell consecutivamente. El agente lanza un paquete Cosmos Sync.app firmado y notarizado que se incluye dentro del paquete npm y se copia en ~/Applications/Cosmos Sync.app en el momento de la instalación.

npx -y @polarity-lab/cosmos-mcp daemon install

Después de la instalación, otorga al paquete Acceso completo al disco una vez:

abre Configuración del Sistema → Privacidad y Seguridad → Acceso completo al disco
haz clic en +, luego arrastra ~/Applications/Cosmos Sync.app a la lista
asegúrate de que la casilla junto a él esté activada
ejecuta cosmos-mcp daemon kick para activar un tick ahora

La sincronización del navegador funciona sin ese paso. iMessage y Calendar lo necesitan porque leen bases de datos SQLite protegidas por TCC en el lado del usuario. cosmos-mcp daemon status informa el id del equipo de firma, las rutas del plist y del runner, y si launchd tiene cargado el agente. cosmos-mcp daemon uninstall elimina el plist, el runner y ~/Applications/Cosmos Sync.app.

Configuración

Variable de entorno	Predeterminado	Cuándo la estableces
`COSMOS_URL`	`https://cosmos.polarity-lab.com`	Anula el endpoint de la API de cosmos.
`COSMOS_TOKEN`	(del llavero)	Clave por usuario `pmk_...` para subcomandos del CLI. Tiene prioridad sobre la entrada del llavero de macOS. Establece esto en CI.
`COSMOS_MCP_KEY`	(del archivo de token)	Clave por usuario `pmk_...`. Se respeta por compatibilidad con versiones anteriores.
`COSMOS_USER_ID`	(del archivo de token)	Id de usuario de Polarity.
`COSMOS_SYSTEM_KEY`	(sin establecer)	Modo de un solo inquilino. Envía `X-System-Key` en lugar de `X-MCP-Key`. Requiere `COSMOS_USER_ID`. Para pruebas internas antes de que se implementen claves por usuario.

La propuesta en tres líneas

Tus herramientas de IA conocen fragmentos de ti. No se les permite compartirlos. Cosmos es la capa que se los permite. Tú tienes la clave. El grafo es portátil. Cuando te vas, te llevas el entendimiento contigo.

Licencia

MIT.