Cosmos-mcp is Cosmos's MCP server and local sync package, with the goal of letting every AI client a user uses share the same personal knowledge graph, rather than each maintaining its own private graph that is disconnected from the others. The official description states that Claude, ChatGPT, Cursor, and others each build private graphs about the user, do not communicate with one another, and do not belong to the user; Cosmos, by contrast, centralizes the knowledge graph in one place, and any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, Zed, Continue) reads from and writes to the same graph. When an agent discovers persistent information about the user, it writes it to the graph; when the user switches tools, the graph migrates along with them. What the user holds is a .polarity file, and the integration layer belongs to the user rather than to the platform.
In terms of main capabilities, cosmos-mcp provides an MCP server containing eleven tools, of which four read and seven write. It supports syncing data from multiple sources: iMessage, browser history, calendar, Claude Desktop session records, shell history, and note sources such as Notion and Obsidian. The MCP read tools see the contents of all sources through the same view. Unchanged pages are skipped on the server side, so re-syncing a quiet vault or a stable Notion workspace is extremely low-cost; iMessage sync is also incremental, based on the watermark from the last successful run, and repeated runs when there are no new messages produce no additional operations.
iMessage sync reads the local Messages database through the imessage subcommand and writes each conversation to the graph. It uses three-rule filtering (senders who do not reply, short numbers, low-activity contacts) to keep the graph clean, and resolves phone numbers and email addresses to real contact names through AddressBook. Reading takes place locally on the Mac, and only extracted and normalized conversation turns enter the user's Cosmos graph.
Claude Desktop sync monitors Claude Code session records through the claude-desktop subcommand and writes each turn to the graph. The desktop chat interface itself stores conversations on the server side, so the disk source that can be monitored in real time is ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. Tool use blocks, hook pipelines, and sub-intelligSidechain rounds are stripped on the client side, and only the text visible between the user and the assistant is sent. Each session id becomes an independent thread node, keyed by (user_id, "claude-desktop", session_id).
In terms of usage, macOS provides a one-line install: install the MCP server, register cosmos-mcp://, configure Claude Desktop, Claude Code, Cursor, Codex, Zed, and Continue, and install Cosmos Sync.app so that iMessage, browser history, calendar, Claude Desktop records, and shell history can sync in the background. Linux and Windows only install the MCP server path. There are two ways to obtain a pmk_… key: the automatic way is to log in at cosmos.polarity-lab.com/connectors and click "open in cosmos-mcp"; the operating system opens a one-time handler that writes the key into the system keychain, and the user never sees the raw key; this deep link requires the URL scheme to be registered first, places a small .app in ~/Library/Application Support/cosmos-mcp/, and registers cosmos-mcp:// with Launch Services, macOS only. The manual way is that if you already have a pmk_… key or do not want to install the handler, the CLI verifies the key with cosmos, then stores it in the macOS system keychain under the service name cosmos-mcp-key; subsequent imessage sync, browser sync, and calendar sync calls read from the keychain, with no environment variable needed. For CI scenarios, you can set COSMOS_TOKEN=pmk_…, which takes precedence over the keychain.
For manual MCP configuration, the installer handles configuration for common clients; if connecting manually, you can point to this package. Another way opens a browser, logs in at cosmos.polarity-lab.com and approves a per-user key, the token lands in ~/.config/cosmos-mcp/token (0600), and then any MCP client can be pointed to it. This configuration can be placed in Claude Desktop's ~/Library/Application Support/Claude/claude_desktop_config.json, Cursor's .cursor/mcp.json, or the equivalent file for the corresponding client.
For background sync (macOS), cosmos-mcp daemon install places a LaunchAgent that triggers every four hours, running browser, iMessage, calendar, claude-desktop, and shell history sync in sequence. The agent launches a signed and notarized Cosmos Sync.app bundle, which is distributed with the npm package and copied to ~/Applications/Cosmos Sync.app during installation. After installation, you need to grant the bundle Full Disk Access once: open System Settings → Privacy & Security → Full Disk Access, click +, drag ~/Applications/Cosmos Sync.app into the list, make sure its checkbox is enabled, then run cosmos-mcp daemon kick to trigger it immediately. Browser sync does not require this step; iMessage and calendar do, because they read user-side SQLite databases protected by TCC. cosmos-mcp daemon status reports the signing team id, plist and runner paths, and whether launchd has loaded the agent; cosmos-mcp daemon uninstall removes the plist, runner, and ~/Applications/Cosmos Sync.app.
Applicable scenarios include: wanting multiple AI clients to share the same personal context and avoid repeatedly describing yourself; needing to bring local messages, browsing history, calendar, and terminal history into a personal knowledge graph; and wanting data to be portable and to take your understanding with you when leaving a platform. In terms of limitations, the official materials do not provide pricing, fees, platform support details (other than full sync on macOS and only the MCP server path on Linux/Windows), effect promises, or specific performance data; some features depend on macOS system permissions and the keychain, and iMessage and calendar sync require Full Disk Access.
