Docs

Connect your agent

This page tells you how to give your coding agents Pensieve as an MCP server, and what each add-on does.

One command for every agent

pensieve integrate recommended

This command finds the agents on your computer. An agent counts as installed when its settings folder exists. For each agent, the command adds:

Pensieve as an MCP server, for every project.
The instructions block, where the agent has a global instructions file. It says to search with Pensieve before grep, and to offer to close the thread closest to done.
The pensieve-search skill.
For Claude Code, three hooks (see Claude Code).

Restart each agent that is open. To see what is available and what is installed, run pensieve integrate with no items.

Each agent

Agent	MCP id	MCP settings file	Instructions
Claude Code	`claude-mcp`	`~/.claude.json` (through `claude mcp add --scope user`)	`~/.claude/CLAUDE.md`
Codex	`codex-mcp`	`~/.codex/config.toml`	`~/.codex/AGENTS.md`
Cursor	`cursor-mcp`	`~/.cursor/mcp.json`	Copy into the agent's rules
Gemini CLI	`gemini-mcp`	`~/.gemini/settings.json`	`~/.gemini/GEMINI.md`
Qwen Code	`qwen-mcp`	`~/.qwen/settings.json`	`~/.qwen/QWEN.md`
Windsurf	`windsurf-mcp`	`~/.codeium/windsurf/mcp_config.json`	Copy into the agent's rules
Claude Desktop	`claude-desktop-mcp`	`~/Library/Application Support/Claude/claude_desktop_config.json`	Copy into the agent's rules
VS Code	`vscode-mcp`	`~/Library/Application Support/Code/User/mcp.json`	Copy into the agent's rules

Any other MCP client can use Pensieve too. It speaks stdio through pensieve mcp, and streamable HTTP at http://127.0.0.1:8765/mcp. pensieve mcp starts the backend if it is not running.

{"mcpServers": {"pensieve": {"command": "pensieve", "args": ["mcp"]}}}

Scopes

Each agent connection works in a scope: a part of the index. Every tool obeys the scope. Pensieve refuses an item outside it.

auto is the default for pensieve mcp. It uses the folder that the agent started in. If a named scope includes that repo, the agent gets that scope. If not, it gets the repo, its worktrees and the agent sessions in it. Outside a repo, auto is everything.
Named scopes are lists of sources, for example the repos and documents of one project. Make them in Settings → Scopes. A scope only filters the index, so nothing is indexed twice.
HTTP connections cannot see the agent's folder. Give a scope in the URL: ?scope=payments. With no scope, an HTTP connection gets everything.

pensieve mcp --scope payments     # stdio, one named scope
pensieve mcp --all-tools          # also the tools that change Pensieve's settings

In a repo that Pensieve does not index, search tells the agent to use grep. It does not return code from your other repos.

Add-ons

Agents grep by habit, also with Pensieve connected. The add-ons make them use it. Install them from Settings → Agents → Agent add-ons, or with pensieve integrate.

Id	What it does	Recommended
`claude-mcp`, `codex-mcp`, `cursor-mcp`, `gemini-mcp`, `qwen-mcp`, `windsurf-mcp`, `claude-desktop-mcp`, `vscode-mcp`	Pensieve as the agent's MCP server, for every project. In each settings file, Pensieve changes only its own entry.	Yes
`claude`, `codex`, `gemini`, `qwen`	The instructions block in the agent's global instructions file. It tells the agent to call Pensieve `search` before Grep or Glob for each code lookup. It also tells the agent to call `threads` at the start of a session and at natural pauses, and to offer to close the thread closest to done.	Yes
`pensieve-search`	A skill: query styles, when to use grep, similar code before new code, past sessions.	Yes
`pensieve-teammates`	A skill: who knows an area, from git blame, and a draft question. It never sends a message.	No
`pensieve-plan`	A skill: plans for new code list code to reuse, earlier attempts, people to ask and knowledge risks.	No
`pensieve-wrap-up`	A skill: gets the threads closest to done and does the steps that close them in git, GitHub and the tracker. It asks before a merge or a close.	No
`claude-hook`, `claude-repo-check`, `claude-prompt-search`, `claude-search-gate`	Claude Code hooks (see Claude Code). The search gate makes Claude search Pensieve before it greps.	Yes

Skills go once into ~/.agents/skills, the user skills folder that many agents read. Claude Code reads only its own folder, so it gets a link in ~/.claude/skills. Pensieve makes no folder for an agent that is not installed.

pensieve integrate cursor-mcp codex                  # only these
pensieve integrate pensieve-teammates pensieve-plan  # the optional skills
pensieve integrate claude --remove                   # removes exactly what was added

Something wrong or missing? Tell us on GitHub.