Cosmos

sua exocortex de IA

Documentação

cosmos-mcp

Um exocórtex. Todos os agentes.
_{Servidor MCP para o seu grafo Cosmos.}

Cada IA que você usa está construindo seu próprio grafo privado sobre você. O Claude tem um. O ChatGPT tem um. O Cursor tem um. Nenhum deles conversa entre si, e nenhum deles é seu.

O Cosmos inverte isso. Seu grafo de conhecimento vive em um único lugar, e qualquer cliente compatível com MCP (Claude Code, Claude Desktop, Cursor, Codex, Zed, Continue) lê e escreve no mesmo grafo. Quando um agente percebe algo duradouro sobre você, isso entra no grafo. Quando você troca de ferramenta, o grafo acompanha. O usuário, não a plataforma, é dono da camada de integração.

O que você carrega é um arquivo .polarity. Seu.

Instalação em uma linha

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

No macOS, isso instala o servidor MCP, registra o cosmos-mcp://, configura Claude Desktop, Claude Code, Cursor, Codex, Zed e Continue, e então instala o Cosmos Sync.app para que iMessage, histórico do navegador, calendário, transcrições do Claude Desktop e histórico do shell possam sincronizar em segundo plano. No Linux e no Windows, instala apenas o caminho do servidor MCP.

Se quiser inspecionar antes de alterar qualquer coisa:

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

Provisionamento

Existem duas maneiras de obter uma chave pmk_… no seu Mac.

Automática. Entre em cosmos.polarity-lab.com/connectors, toque em "abrir no cosmos-mcp". O sistema operacional abre um manipulador de uso único que grava a chave no seu chaveiro do sistema. Você nunca vê a chave bruta.

Para que esse link profundo funcione, registre o esquema de URL uma vez:

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

Isso coloca um pequeno .app em ~/Library/Application Support/cosmos-mcp/ e registra o cosmos-mcp:// com o Launch Services. Somente macOS.

Manual. Se você já tem uma chave pmk_…, ou não quer instalar o manipulador:

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

A CLI valida a chave contra o cosmos e a armazena no chaveiro do sistema macOS sob o serviço cosmos-mcp-key. Chamadas subsequentes de imessage sync, browser sync, calendar sync leem do chaveiro. Nenhuma variável de ambiente é necessária.

Confirme o acesso ao iMessage.

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

Verifica se o Acesso Total ao Disco foi concedido e informa quantas conversas estão visíveis. Se você vir uma mensagem EACCES, abra Ajustes do Sistema, Privacidade e Segurança, Acesso Total ao Disco, e adicione o Terminal (ou o aplicativo que executa a CLI).

CI. Defina COSMOS_TOKEN=pmk_… no ambiente. Ele tem precedência sobre o chaveiro, então pipelines existentes continuam funcionando sem alterações.

Configuração manual do MCP

O instalador cuida disso para clientes comuns. Se quiser conectar um cliente manualmente, aponte-o para o pacote.

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

Isso abre seu navegador. Entre em cosmos.polarity-lab.com, aprove uma chave por usuário, e o token fica em ~/.config/cosmos-mcp/token (0600). Então aponte qualquer cliente MCP para ele:

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

Essa configuração vai para ~/Library/Application Support/Claude/claude_desktop_config.json no Claude Desktop, para o seu .cursor/mcp.json no Cursor, e para o equivalente em qualquer outro cliente.

O que você obtém

Onze ferramentas, quatro de leitura, sete de escrita.

Leitura

Ferramenta	Chamadas	O que retorna
`polarity_whoami`	`GET /api/polarity/whoami`	Usuário vinculado + escopos. Sonda barata.
`polarity_export`	`POST /api/polarity/export`	Grafo pessoal completo como JSON `polarity/v1`.
`polarity_get_graph`	`GET /api/polarity`	Visão do grafo, com escopo por entidade (`user`, `cosmos`, `polarity`).
`polarity_ask`	`POST /api/polarity/ask`	Pergunta em linguagem natural sintetizada sobre o grafo.

Escrita

Ferramenta	Chamadas	O que faz
`polarity_observe`	`POST /api/polarity/observe`	Observação livre. O Cosmos extrai.
`polarity_record_event`	`POST /api/polarity/observe` (kind=event)	Algo aconteceu em um ponto no tempo.
`polarity_record_preference`	`POST /api/polarity/observe` (kind=preference)	Um gosto, desgosto, regra de estilo de trabalho.
`polarity_capture_turn`	`POST /api/polarity/capture-turn`	Entrega uma troca inteira usuário/assistente ao cosmos. Extrai todas as observações duráveis em uma única chamada. Prefira isso a múltiplas chamadas de `polarity_observe`.
`polarity_dump`	`POST /api/polarity/dump`	Mensagem curta ancorada por localização.
`polarity_checkin`	`POST /api/polarity/checkin`	Check-in em um waypoint. Dispara detecção de co-presença.
`polarity_declare`	`POST /api/polarity/declare`	Declara presença futura em um waypoint.

Fontes

O servidor MCP é uma forma de escrever no grafo. O Cosmos aceita páginas de fonte de qualquer lugar onde você mantém notas, e as ferramentas de leitura do MCP veem tudo pela mesma visão.

Fonte	Como conecta	O que entra
iMessage	CLI local: `npx -y @polarity-lab/cosmos-mcp imessage sync`. Somente Mac. Conceda Acesso Total ao Disco ao Terminal primeiro.	Turnos conversacionais de `chat.db`, com conteúdo de texto. Pessoas aparecem como nós de pessoa no seu grafo, dimensionados pelo peso da conversa, nomeados via seu AddressBook local, datados pelos seus timestamps reais de mensagem.
Claude Desktop	CLI local: `npx -y @polarity-lab/cosmos-mcp claude-desktop sync`. Lê transcrições de sessão do Claude Code em `~/.claude/projects/`.	Cada sessão do Claude Code vira um nó de thread; turnos de usuário e assistente entram em `conversation_turns` com texto completo. O encanamento de uso de ferramentas é removido no lado do cliente.
Histórico do shell	CLI local: `npx -y @polarity-lab/cosmos-mcp shell-history sync`. Lê `~/.zsh_history` (com fallback para bash/fish) com um watermark de deslocamento de bytes.	Cada janela de sincronização entra como um `source_page` chaveado por `shell-history:<sync-iso>`, corpo = comandos unidos por nova linha. Comandos triviais (`ls`, `cd ..`, caracteres únicos) e duplicatas consecutivas são filtrados no lado do cliente.
Notion	OAuth em cosmos.polarity-lab.com/connectors. Escolha as páginas e bancos de dados que quer compartilhar.	Cada página do Notion vira um nó `source_page`, chaveado pelo id do Notion, mantido atualizado por uma sincronização diária.
Obsidian	Plugin da comunidade: polarity-lab/obsidian-cosmos. Cole sua chave `pmk_`, aponte para seu cofre.	Cada nota vira um nó `source_page` chaveado pelo caminho relativo ao cofre. Tags e wikilinks resolvem em arestas.
Clientes MCP	Este pacote.	Observações, eventos, preferências, dumps de localização, check-ins, declarações.
API direta	`POST /api/polarity/observe` com sua chave.	Qualquer coisa que você possa expressar como observação.

Páginas inalteradas são ignoradas no lado do servidor, então re-sincronizar um cofre parado ou um workspace estável do Notion custa quase nada. A sincronização do iMessage também é incremental, com watermark na última execução bem-sucedida, então reexecutá-la é um no-op até chegarem novas mensagens.

Sincronização do iMessage

cosmos-mcp inclui um subcomando imessage que lê seu banco de dados local de Mensagens e coloca cada conversa no seu 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

Um filtro de lixo com três regras (remetentes sem resposta, números de código curto, contatos de baixo volume) mantém o grafo limpo. Seu AddressBook resolve números de telefone e e-mails em nomes reais de contato. A leitura é local ao seu Mac; apenas os turnos extraídos e normalizados vão para o seu grafo cosmos, que é sua conta.

Sincronização do Claude Desktop

cosmos-mcp inclui um subcomando claude-desktop que observa transcrições de sessão do Claude Code e coloca cada turno no seu grafo. A própria superfície de chat do desktop armazena conversas no lado do servidor, então a fonte ao vivo e observável em disco é ~/.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

Blocos de uso de ferramentas, encanamento de hooks e turnos de subagentes (sidechain) são removidos no lado do cliente; apenas o texto visível trocado entre usuário e assistente é enviado. Cada id de sessão vira seu próprio nó de thread, chaveado por (user_id, "claude-desktop", session_id).

Sincronização em segundo plano (macOS)

cosmos-mcp daemon install coloca um LaunchAgent que dispara a cada quatro horas e executa as sincronizações de navegador, iMessage, calendário, claude-desktop e histórico do shell em sequência. O agente dispara um bundle Cosmos Sync.app assinado e notarizado que vem dentro do pacote npm e é copiado para ~/Applications/Cosmos Sync.app na instalação.

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

Após a instalação, conceda Acesso Total ao Disco ao bundle uma vez:

abra Ajustes do Sistema → Privacidade e Segurança → Acesso Total ao Disco
clique em +, então arraste ~/Applications/Cosmos Sync.app para a lista
certifique-se de que a caixa de seleção ao lado dele está marcada
execute cosmos-mcp daemon kick para disparar um tick agora

A sincronização do navegador funciona sem esse passo. iMessage e Calendário precisam dele porque leem bancos de dados SQLite protegidos por TCC no lado do usuário. cosmos-mcp daemon status informa o id da equipe de assinatura, os caminhos do plist + runner, e se o launchd tem o agente carregado. cosmos-mcp daemon uninstall remove o plist, o runner e o ~/Applications/Cosmos Sync.app.

Configuração

Variável de ambiente	Padrão	Quando definir
`COSMOS_URL`	`https://cosmos.polarity-lab.com`	Substitui o endpoint da API do cosmos.
`COSMOS_TOKEN`	(do chaveiro)	Chave `pmk_...` por usuário para subcomandos da CLI. Tem precedência sobre a entrada do chaveiro do macOS. Defina isso no CI.
`COSMOS_MCP_KEY`	(do arquivo de token)	Chave `pmk_...` por usuário. Honrada para compatibilidade retroativa.
`COSMOS_USER_ID`	(do arquivo de token)	Id de usuário do Polarity.
`COSMOS_SYSTEM_KEY`	(não definido)	Modo de tenant único. Envia `X-System-Key` em vez de `X-MCP-Key`. Requer `COSMOS_USER_ID`. Para testes internos antes da implantação de chaves por usuário.

A proposta em três linhas

Suas ferramentas de IA conhecem fragmentos de você. Elas não têm permissão para compartilhar. O Cosmos é a camada que permite isso. Você segura a chave. O grafo é portátil. Quando você sai, leva o entendimento com você.

Licença

MIT.