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 sobre ti. Claude tiene uno. ChatGPT tiene uno. Cursor tiene uno. Ninguno se comunica con los demá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://, configura 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 nada:

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ática. 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

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

Confirma el acceso a iMessage.

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

Verifica que se haya otorgado Acceso Total al Disco e informa cuántos chats son visibles. Si ves un mensaje EACCES, abre Configuración del Sistema, Privacidad y Seguridad, Acceso Total al Disco, y agrega Terminal (o la aplicación que ejecute la 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 a mano, 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 aterriza 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, y el equivalente para el cliente que sea.

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 JSON `polarity/v1`.
`polarity_get_graph`	`GET /api/polarity`	Vista del 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)	Un gusto, disgusto, regla de estilo de trabajo.
`polarity_capture_turn`	`POST /api/polarity/capture-turn`	Entrega un intercambio completo usuario/asistente a cosmos. Extrae cada observación duradera en una sola llamada. Prefiérelo sobre múltiples llamadas a `polarity_observe`.
`polarity_reconstruct_hours`	`POST /api/polarity/reconstruct-hours`	Persiste recibos de horas de vida en el mapa de habilidades (solo por usuario). Úsalo desde Cursor/IDE de Cosmos después de trabajo sustancial.
`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 fuente 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	Lo que aterriza
iMessage	CLI local: `npx -y @polarity-lab/cosmos-mcp imessage sync`. Solo Mac. Otorga Acceso Total al Disco a Terminal primero.	Turnos conversacionales de `chat.db`, con contenido de texto. Las personas aparecen como nodos de persona en tu grafo, dimensionados por peso conversacional, nombrados mediante tu AddressBook 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 aterrizan en `conversation_turns` con texto completo. La plomería de uso de herramientas se elimina del lado del cliente.
Historial de shell	CLI local: `npx -y @polarity-lab/cosmos-mcp shell-history sync`. Lee `~/.zsh_history` (con respaldo a bash/fish) con una marca de agua de desplazamiento de bytes.	Cada ventana de sincronización aterriza como un `source_page` claveado por `shell-history:<sync-iso>`, cuerpo = comandos unidos por saltos de línea. Los comandos triviales (`ls`, `cd ..`, caracteres individuales) y duplicados consecutivos se filtran del 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`, claveado por id de Notion, mantenido fresco por 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` claveado por ruta relativa a la bóveda. Las etiquetas y 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 del lado del servidor, por lo que re-sincronizar una bóveda tranquila o un espacio de trabajo estable de Notion 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 re-ejecutarla es una no-operación hasta que lleguen nuevos mensajes.

Sincronización de iMessage

cosmos-mcp incluye un subcomando imessage que lee tu base de datos local de Messages y aterriza 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 limpio el grafo. Tu AddressBook resuelve números de teléfono y correos electrónicos en nombres de contacto reales. La lectura es local a 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 aterriza cada turno en tu grafo. La superficie de chat de escritorio en sí almacena conversaciones del lado del servidor, por lo que la fuente viva y observable en disco 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, la plomería de hooks y los turnos de sub-agentes (sidechain) se eliminan del 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, claveado por (user_id, "claude-desktop", session_id).

Sincronización en segundo plano (macOS)

cosmos-mcp daemon install coloca un LaunchAgent que se ejecuta cada cuatro horas y ejecuta las sincronizaciones de navegador, iMessage, calendario, claude-desktop e historial de shell de forma consecutiva. El agente dispara un paquete Cosmos Sync.app firmado y notarizado que viaja 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 Acceso Total al Disco al paquete una vez:

abre Configuración del Sistema → Privacidad y Seguridad → Acceso Total 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 disparar un tick ahora

La sincronización del navegador funciona sin ese paso. iMessage y Calendario lo necesitan porque leen bases de datos SQLite protegidas por TCC del lado del usuario. cosmos-mcp daemon status informa el id del equipo de firma, las rutas del plist + runner, y si launchd tiene el agente cargado. 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`	Sobrescribe el endpoint de la API de cosmos.
`COSMOS_TOKEN`	(desde el llavero)	Clave `pmk_...` por usuario para subcomandos de CLI. Tiene prioridad sobre la entrada del llavero de macOS. Establécelo en CI.
`COSMOS_MCP_KEY`	(desde el archivo de token)	Clave `pmk_...` por usuario. Se honra por compatibilidad inversa.
`COSMOS_USER_ID`	(desde el 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.

El discurso 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.