Docs

Connections

This page tells you how Pensieve collects tickets, messages and pages from your MCP servers, and how it keeps the collection read-only.

A connection is an MCP server that Pensieve collects data from. Pensieve writes each item as a Markdown file in ~/.pensieve/connections and indexes it like a document. Each item keeps a list of its changes over time. Collected tickets and messages also join your threads.

Each connection is off until you switch it on in Settings → Sources.

Where the servers come from

Pensieve finds your MCP servers by itself. It never starts an agent of its own:

Your agents' servers. Pensieve reads the MCP settings of Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Windsurf, Claude Desktop and VS Code. It connects to those servers itself, with the credentials in those settings.
Your own servers. Add a server in Sources. Give a URL with headers, or a command with environment variables. Pensieve does not show the header or environment values again. They stay in ~/.pensieve/settings.json, which only you can read.
Your agent sessions. The results that your agents already got from MCP tools. Pensieve fetches nothing new for this source.

If Pensieve has no recipe for a server, your agent chooses the search calls as a pending job, and Pensieve makes them.

How Pensieve keeps it read-only

Pensieve calls a tool only if the tool is read-only. A tool is read-only when these conditions are true:

Its name has a read verb, such as get, list, search, read or fetch.
Its name has no write verb, such as create, update, send or delete. The list has almost 100 write verbs.
The server does not mark it readOnlyHint: false or destructiveHint: true.

A server's hints can only make the rule stricter. Pensieve never calls a write tool.

Private messages

Pensieve marks an item as private when it comes from a direct message, a group message or a private channel. It also marks every item from a tool that can read those, such as a tool with “private” or “dm” in its name. Private items are context for your own threads and agents. A shared thread leaves them out whole.

When Pensieve collects

Setting	Default	What it does
`connections_every_hours`	6	How often Pensieve collects from each connection that is on. 0 collects only when you ask.
`connections_days`	30	How far back the first collection goes.

Collect now in Sources collects at once.

See Privacy and data for what goes over the network when Pensieve collects.

Something wrong or missing? Tell us on GitHub.