Cosmos-mcp 是 Cosmos 的 MCP 服务器与本地同步包，目标是让用户使用的每个 AI 客户端共享同一份个人知识图谱，而不是各自维护互不相通的私有图谱。官方描述称，Claude、ChatGPT、Cursor 等各自构建关于用户的私有图谱，彼此不通信且不属于用户；Cosmos 则把知识图谱集中在一处，任何支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor、Codex、Zed、Continue）都读写同一个图谱。当智能体发现关于用户的持久信息时，会写入图谱；用户切换工具时，图谱随之迁移。用户持有的是 .polarity 文件，集成层归用户而非平台所有。
主要能力方面，cosmos-mcp 提供 MCP 服务器，包含十一个工具，其中四个读取、七个写入。它支持从多种来源同步数据：iMessage、浏览器历史、日历、Claude Desktop 会话记录、shell 历史，以及 Notion、Obsidian 等笔记来源。MCP 读取工具通过同一视图看到所有来源的内容。未变更的页面会在服务端跳过，因此重新同步安静的 vault 或稳定的 Notion 工作区开销极低；iMessage 同步也是增量的，以上次成功运行的水位线为准，没有新消息时重复运行不会产生额外操作。
iMessage 同步通过 imessage 子命令读取本地 Messages 数据库，把每个会话写入图谱。它使用三条规则的过滤（不回复的发送者、短号码、低活跃联系人）保持图谱干净，并通过 AddressBook 把电话号码和邮箱解析为真实联系人姓名。读取在 Mac 本地进行，只有提取并规范化后的对话轮次进入用户的 Cosmos 图谱。
Claude Desktop 同步通过 claude-desktop 子命令监视 Claude Code 会话记录，把每一轮写入图谱。桌面聊天界面本身在服务端存储对话，因此可实时监视的磁盘来源是 ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl。工具使用块、钩子管道和子智能体（sidechain）轮次会在客户端被剥离，只发送用户与助手之间可见的文本。每个会话 id 成为独立的线程节点，以 (user_id, "claude-desktop", session_id) 为键。
使用方式上，macOS 提供一行安装：安装 MCP 服务器、注册 cosmos-mcp://、配置 Claude Desktop、Claude Code、Cursor、Codex、Zed 和 Continue，并安装 Cosmos Sync.app，使 iMessage、浏览器历史、日历、Claude Desktop 记录和 shell 历史可在后台同步。Linux 和 Windows 仅安装 MCP 服务器路径。获取 pmk_… 密钥有两种方式：自动方式是在 cosmos.polarity-lab.com/connectors 登录并点击“open in cosmos-mcp”，操作系统打开一次性处理器把密钥写入系统钥匙串，用户不会看到原始密钥；该深链需要先注册 URL scheme，会在 ~/Library/Application Support/cosmos-mcp/ 放置一个小型 .app 并向 Launch Services 注册 cosmos-mcp://，仅限 macOS。手动方式是若已有 pmk_… 密钥或不想安装处理器，CLI 会向 cosmos 验证密钥，然后存入 macOS 系统钥匙串，服务名为 cosmos-mcp-key，后续 imessage sync、browser sync、calendar sync 调用从钥匙串读取，无需环境变量。CI 场景可设置 COSMOS_TOKEN=pmk_…，其优先级高于钥匙串。
手动 MCP 配置方面，安装器会为常见客户端处理配置；若手动连接，可指向该包。另一种方式会打开浏览器，在 cosmos.polarity-lab.com 登录并批准每用户密钥，令牌落在 ~/.config/cosmos-mcp/token（0600），然后让任意 MCP 客户端指向它。该配置可放入 Claude Desktop 的 ~/Library/Application Support/Claude/claude_desktop_config.json、Cursor 的 .cursor/mcp.json 或对应客户端的等效文件。
后台同步（macOS）方面，cosmos-mcp daemon install 会放置一个 LaunchAgent，每四小时触发一次，依次运行浏览器、iMessage、日历、claude-desktop 和 shell 历史同步。该代理会启动一个签名并公证的 Cosmos Sync.app 包，该包随 npm 包分发，安装时复制到 ~/Applications/Cosmos Sync.app。安装后需为该包授予一次完全磁盘访问权限：打开系统设置 → 隐私与安全性 → 完全磁盘访问，点击 +，把 ~/Applications/Cosmos Sync.app 拖入列表，确保其复选框开启，然后运行 cosmos-mcp daemon kick 立即触发一次。浏览器同步无需此步骤；iMessage 和日历需要，因为它们读取用户侧受 TCC 保护的 SQLite 数据库。cosmos-mcp daemon status 报告签名团队 id、plist 与 runner 路径以及 launchd 是否加载代理；cosmos-mcp daemon uninstall 移除 plist、runner 和 ~/Applications/Cosmos Sync.app。
适用场景包括：希望多个 AI 客户端共享同一份个人上下文、避免重复描述自己；需要把本地消息、浏览记录、日历和终端历史纳入个人知识图谱；以及希望数据可携带、离开平台时带走理解。限制方面，官方资料未提供价格、收费、平台支持细节（除 macOS 完整同步与 Linux/Windows 仅 MCP 服务器路径外）、效果承诺或具体性能数据；部分功能依赖 macOS 系统权限与钥匙串，iMessage 和日历同步需要完全磁盘访问。
