cosmos-mcp

cosmos-mcp

一个外部皮层，服务每个 Agent。
_{适用于 Cosmos 图谱的 MCP 服务。}

---

你使用的每个 AI 都在构建一张关于你的私人图谱。Claude 有一张，ChatGPT 有一张，Cursor 也有一张。它们彼此无法沟通，而且这些图谱都不属于你。

Cosmos 则反其道而行。你的知识图谱保存在一个地方，任何支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor、Codex、Zed、Continue）都能读取和写入同一张图谱。当某个 Agent 发现了关于你的重要信息，它就会进入图谱。当你切换工具时，图谱也会随之而来。集成层归用户所有，而非平台。

你随身携带的是一个 .polarity 文件。它属于你。

一行命令安装

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

在 macOS 上，这会安装 MCP 服务、注册 cosmos-mcp://，为 Claude Desktop、Claude Code、Cursor、Codex、Zed 和 Continue 配置连接，然后安装 Cosmos Sync.app，以便在后台同步 iMessage、浏览器历史记录、日历、Claude Desktop 对话记录和 shell 历史记录。在 Linux 和 Windows 上，只会安装 MCP 服务路径。

如果你想先检查，再进行任何更改：

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

配置

有两种方式可以将 pmk_… 密钥添加到 Mac。

自动方式。 在 cosmos.polarity-lab.com/connectors 登录，然后点击“在 cosmos-mcp 中打开”。操作系统会打开一个一次性处理程序，将密钥写入系统钥匙串。你不会看到原始密钥。

要让这个深层链接生效，请先注册一次 URL 方案：

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

这会在 ~/Library/Application Support/cosmos-mcp/ 中放置一个小型 .app，并通过 Launch Services 注册 cosmos-mcp://。仅适用于 macOS。

手动方式。 如果你已有 pmk_… 密钥，或者不想安装处理程序：

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

CLI 会向 cosmos 验证密钥，然后将其存储在 macOS 系统钥匙串中，服务名为 cosmos-mcp-key。之后调用 imessage sync、browser sync、calendar sync 时，会从钥匙串读取密钥。无需环境变量。

确认 iMessage 访问权限。

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

验证是否已授予“完全磁盘访问权限”，并报告可见的聊天数量。如果看到 EACCES 消息，请打开“系统设置”中的“隐私与安全性”>“完全磁盘访问权限”，然后添加 Terminal（或运行 CLI 的其他应用）。

CI。 在环境中设置 COSMOS_TOKEN=pmk_…。它的优先级高于钥匙串，因此现有流水线无需更改即可继续运行。

手动配置 MCP

安装程序会为常用客户端处理此配置。如果你想手动连接客户端，请将其指向该软件包。

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

这会打开浏览器。在 cosmos.polarity-lab.com 登录并批准一个个人密钥，然后令牌会保存到 ~/.config/cosmos-mcp/token（0600）。接着，将任意 MCP 客户端指向该令牌：

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

对于 Claude Desktop，将此配置放入 ~/Library/Application Support/Claude/claude_desktop_config.json；对于 Cursor，放入 .cursor/mcp.json；其他客户端则放入相应配置文件。

你将获得

共 11 个工具，其中 4 个读取工具、7 个写入工具。

读取

工具	调用	返回内容
polarity_whoami	GET /api/polarity/whoami	已绑定的用户和作用域。轻量探测。
polarity_export	POST /api/polarity/export	完整的个人图谱，格式为 polarity/v1 JSON。
polarity_get_graph	GET /api/polarity	按实体（user、cosmos、polarity）限定范围的图谱视图。
polarity_ask	POST /api/polarity/ask	根据图谱综合生成的自然语言问题回答。

写入

工具	调用	功能
polarity_observe	POST /api/polarity/observe	自由格式观察记录。由 Cosmos 提取信息。
polarity_record_event	POST /api/polarity/observe (kind=event)	记录某个时间点发生的事情。
polarity_record_preference	POST /api/polarity/observe (kind=preference)	记录喜好、厌恶或工作方式规则。
polarity_capture_turn	POST /api/polarity/capture-turn	将一整段用户/助手对话交给 cosmos。在一次调用中提取所有持久性观察记录。优先使用此工具，而不是多次调用 polarity_observe。
polarity_reconstruct_hours	POST /api/polarity/reconstruct-hours	将生活时长凭证持久化到技能图谱天空中（仅针对用户）。在 Cursor/Cosmos IDE 中完成实质性工作后使用。
polarity_dump	POST /api/polarity/dump	带有位置锚点的简短消息。
polarity_checkin	POST /api/polarity/checkin	在一个路径点签到。触发共处检测。
polarity_declare	POST /api/polarity/declare	声明未来将在某个路径点出现。

来源

MCP 服务是向图谱写入信息的一种方式。Cosmos 接受来自你存放笔记的任何位置的来源页面，MCP 读取工具也能通过同一个视图查看所有内容。

来源	连接方式	写入内容
iMessage	本地 CLI：npx -y @polarity-lab/cosmos-mcp imessage sync。仅限 Mac。请先授予 Terminal“完全磁盘访问权限”。	从 chat.db 导入对话轮次及其文本内容。联系人会作为人物节点出现在你的图谱中，节点大小取决于对话权重，名称来自本地 AddressBook，日期采用真实消息时间戳。
Claude Desktop	本地 CLI：npx -y @polarity-lab/cosmos-mcp claude-desktop sync。读取 ~/.claude/projects/ 中的 Claude Code 会话记录。	每个 Claude Code 会话都会成为一个线程节点；用户和助手的对话轮次会连同完整文本写入 conversation_turns。工具使用相关的底层信息会在客户端剔除。
Shell 历史记录	本地 CLI：npx -y @polarity-lab/cosmos-mcp shell-history sync。读取 ~/.zsh_history（若不可用，则回退到 bash/fish），并使用字节偏移水位标记。	每个同步窗口会作为一个 source_page 写入，以 shell-history:<sync-iso> 为键，正文由换行符连接各条命令。简单命令（ls、cd ..、单个字符）和连续重复命令会在客户端过滤。
Notion	在 cosmos.polarity-lab.com/connectors 上通过 OAuth 连接。选择要共享的页面和数据库。	每个 Notion 页面都会成为一个 source_page 节点，以 Notion ID 为键，并通过每日同步保持最新。
Obsidian	社区插件：polarity-lab/obsidian-cosmos。粘贴你的 pmk_ 密钥，并指定你的库。	每条笔记都会成为一个 source_page 节点，以库内相对路径为键。标签和维基链接会解析为边。
MCP 客户端	此软件包。	观察记录、事件、偏好、位置消息、签到和声明。
直接 API	使用你的密钥调用 POST /api/polarity/observe。	任何可表达为观察记录的内容。

未更改的页面会在服务端跳过，因此重新同步没有新内容的库或保持稳定的 Notion 工作区几乎不会产生额外开销。iMessage 同步也是增量式的，会记录上次成功运行的水位标记，因此在收到新消息之前重新运行不会产生任何操作。

iMessage 同步

cosmos-mcp 附带一个 imessage 子命令，可读取本地 Messages 数据库，并将每段对话写入你的图谱。

# 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

一个包含三条规则的劣质内容过滤器（不回复的发送者、短代码号码、低频联系人）可保持图谱整洁。AddressBook 会将电话号码和电子邮件解析为真实的联系人姓名。读取操作在本地 Mac 上进行；只有提取并规范化后的对话轮次会写入你的 cosmos 图谱，也就是你的账户。

Claude Desktop 同步

cosmos-mcp 附带一个 claude-desktop 子命令，可监视 Claude Code 会话转录，并将每轮对话写入你的图谱。桌面聊天界面本身会在服务端存储对话，因此磁盘上可实时监视的来源是 ~/.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

工具调用块、钩子流程以及子 Agent（sidechain）对话轮次会在客户端剔除；只会传输用户与助手之间可见的文本。每个会话 ID 都会成为独立的线程节点，键为 (user_id, "claude-desktop", session_id)。

后台同步（macOS）

cosmos-mcp daemon install 会添加一个 LaunchAgent，每四小时运行一次，并依次执行浏览器、iMessage、日历、claude-desktop 和 shell 历史记录的同步。该 Agent 会运行经过签名和公证的 Cosmos Sync.app 程序包；它随 npm 软件包一起发布，并在安装时复制到 ~/Applications/Cosmos Sync.app。

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

安装后，为该程序包授予一次“完全磁盘访问权限”：

1. 打开“系统设置” →“隐私与安全性” →“完全磁盘访问权限”
2. 点击 +，然后将 ~/Applications/Cosmos Sync.app 拖入列表
3. 确保其旁边的复选框已勾选
4. 运行 cosmos-mcp daemon kick，立即触发一次运行

浏览器同步无需执行此步骤。iMessage 和日历同步需要此权限，因为它们会读取用户侧受 TCC 保护的 SQLite 数据库。cosmos-mcp daemon status 会报告签名团队 ID、plist 和 runner 路径，以及 launchd 是否已加载该 Agent。cosmos-mcp daemon uninstall 会移除 plist、runner 和 ~/Applications/Cosmos Sync.app。

配置

环境变量	默认值	设置时机
COSMOS_URL	https://cosmos.polarity-lab.com	覆盖 cosmos API 端点。
COSMOS_TOKEN	（来自钥匙串）	CLI 子命令使用的每用户 pmk_... 密钥。优先于 macOS 钥匙串条目。在 CI 中设置此项。
COSMOS_MCP_KEY	（来自令牌文件）	每用户 pmk_... 密钥。为保持向后兼容而受支持。
COSMOS_USER_ID	（来自令牌文件）	Polarity 用户 ID。
COSMOS_SYSTEM_KEY	（未设置）	单租户模式。发送 X-System-Key，而非 X-MCP-Key。需要 COSMOS_USER_ID。用于部署每用户密钥前的内部测试。

三句话介绍

你的每个 AI 工具都只了解关于你的片段，但它们不能互相共享。 Cosmos 是让它们能够共享的那一层。密钥由你掌握。图谱可移植。 当你离开时，你可以带走这些理解。

许可证

MIT。