teampolarity/cosmos-mcp

One exocortex. Every agent.
MCP server for your Cosmos graph.
---
Every AI you use is building its own private graph of you. Claude has one. ChatGPT has one. Cursor has one. None of them talk to each other, and none of them are yours.
Cosmos inverts that. Your knowledge graph lives in one place, and any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, Zed, Continue) reads and writes to the same one. When an agent notices something durable about you, it lands in the graph. When you switch tools, the graph follows. The user, not the platform, owns the integration layer.
The thing you carry is a .polarity file. Yours.
One-line install
On macOS this installs the MCP server, registers cosmos-mcp://, wires Claude Desktop, Claude Code, Cursor, Codex, Zed, and Continue, then installs Cosmos Sync.app so iMessage, browser history, calendar, Claude Desktop transcripts, and shell history can sync in the background. On linux and windows it installs the MCP server path only.
If you want to inspect before changing anything:
Provisioning
There are two ways to get a pmk_… key onto your Mac.
**Automatic.** Sign in at cosmos.polarity-lab.com/connectors, tap "open in cosmos-mcp." The OS opens a one-shot handler that writes the key into your system keychain. You never see the raw key.
For that deep link to work, register the URL scheme once:
This drops a tiny .app into ~/Library/Application Support/cosmos-mcp/ and registers cosmos-mcp:// with Launch Services. macOS-only.
**Manual.** If you already have a pmk_… key, or you do not want to install the handler:
The CLI validates the key against cosmos, then stores it in the macOS system keychain under service cosmos-mcp-key. Subsequent imessage sync, browser sync, calendar sync calls read from the keychain. No env var needed.
**Confirm iMessage access.**
Verifies Full Disk Access is granted and reports how many chats are visible. If you see an EACCES message, open System Settings, Privacy & Security, Full Disk Access, and add Terminal (or whichever app runs the CLI).
**CI.** Set COSMOS_TOKEN=pmk_… in env. It takes precedence over the keychain, so existing pipelines keep working untouched.
Manual MCP config
The installer handles this for common clients. If you want to wire a client by hand, point it at the package.
This opens your browser. Sign in at cosmos.polarity-lab.com, approve a per-user key, and the token lands at ~/.config/cosmos-mcp/token (0600). Then point any MCP client at it:
That config drops into ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop, your .cursor/mcp.json for Cursor, the equivalent for whichever client.
What you get
Eleven tools, four read, seven write.
**Read**
| Tool | Calls | What it returns |
|---|---|---|
| polarity_whoami | GET /api/polarity/whoami | Bound user + scopes. Cheap probe. |
| polarity_export | POST /api/polarity/export | Full personal graph as polarity/v1 JSON. |
| polarity_get_graph | GET /api/polarity | Graph view, scoped by entity (user, cosmos, polarity). |
| polarity_ask | POST /api/polarity/ask | NL question synthesized over the graph. |
**Write**
| Tool | Calls | What it does |
|---|---|---|
| polarity_observe | POST /api/polarity/observe | Freeform observation. Cosmos extracts. |
| polarity_record_event | POST /api/polarity/observe (kind=event) | Something happened at a point in time. |
| polarity_record_preference | POST /api/polarity/observe (kind=preference) | A like, dislike, working-style rule. |
| polarity_capture_turn | POST /api/polarity/capture-turn | Hand a whole user/assistant exchange to cosmos. Pulls every durable observation in one call. Prefer over multiple polarity_observe calls. |