Docs

Frequently asked questions

This page answers the questions that people ask most about Pensieve.

Is Pensieve free?

Yes. Pensieve is free and open source under the MIT license. The code is on GitHub. There is no account and no paid plan.

Does Pensieve need Apple Silicon?

The app download needs an Apple Silicon Mac with macOS 14 or later. On Linux and Intel Macs, the same install command installs the backend, the MCP server and the Map in your browser. The search panel is macOS only. See Requirements.

Does it work on Linux?

Yes, without the Mac app. The backend indexes, searches and serves MCP to your agents. The Map opens in your browser. The search model runs on PyTorch (CUDA or CPU). pensieve integrate connects the agents whose settings are in your home folder: Claude Code, Codex, Cursor, Gemini CLI, Qwen Code and Windsurf.

Which agents can use it?

Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Windsurf, Claude Desktop and VS Code, with one command. Any other MCP client can connect over stdio or HTTP. See Connect your agent.

Does anything leave my computer?

Your files, code and sessions do not leave because of Pensieve. Indexing and search run locally. Pensieve downloads models, finds updates, fetches your repos' default branches, and collects from connections that you switch on. If your agent is a cloud agent, what it reads goes to its provider. See Privacy and data.

Do I need an AI model?

No. Search, agent context, ownership and knowledge gaps need none. The notes on threads and the written insights come from the engine that you pick at setup: Claude Code with Haiku, the built-in Qwen 3.5 9B on your Mac, or a model server that you run, such as LM Studio.

How do I make my agent use Pensieve and not grep?

Run pensieve integrate recommended. It adds the MCP server, a short “search before you grep” instructions block, and the pensieve-search skill. Without instructions, agents did not call Pensieve in our first test. With them, the agent used Pensieve in all 144 runs of the last benchmark batch.

Is it better than grep?

It finds the right file with fewer tool calls, at lower cost. In our benchmark with Claude Sonnet, the cost per lookup was 18 to 25% lower. Accuracy was 6 points higher in the first batch and level in the later batches. See the benchmark for the method and the limits.

How long does the first index take?

About 500 code files a minute on Apple Silicon. A repo with 35,000 files takes a little more than one hour. Search works while Pensieve indexes. After the first index, a change shows in search about half a second after you save.

Can I limit an agent to one project?

Yes. By default, an agent's scope is the repo that it started in. You can make named scopes in Settings → Scopes, and connect an agent with pensieve mcp --scope <name>. See Scopes.

Does Pensieve read my private messages?

Only if you switch on a connection that can read them. Pensieve marks those items private. They help your own threads and agents. A shared thread leaves them out whole.

For Claude Code, which do I use: the plugin or pensieve integrate?

Use one of them, not both. The plugin does not change your settings files. pensieve integrate also connects your other agents. See Pensieve for Claude Code.

How do I uninstall it?

See Uninstall.

How do I report a bug?

Use Settings → Feedback in the app, or open an issue on GitHub. Agents can call the report_feedback tool. Reports stay on your computer until you send them.

Something wrong or missing? Tell us on GitHub.