Docs

Install Pensieve

This page tells you how to install Pensieve, connect your agents and choose what to index.

Requirements

On Apple Silicon, the search model runs on MLX. On other computers, it runs on sentence-transformers and PyTorch (CUDA or CPU). This makes the install about 650 MB larger.

Install

1. Open Terminal and run the install script:

   curl -fsSL https://pensieve.tools/install.sh | sh

2. Connect the coding agents on your computer:

   pensieve integrate recommended

3. Restart each agent that is open. An agent loads its MCP servers when it starts.
4. Do the setup steps in the app, or ask your agent to do them (see Choose what to index).

You can also give the two commands to your coding agent. When an agent runs the install script, the script installs only and does not open the app.

What the install script does

• On an Apple Silicon Mac: it downloads the latest Pensieve.dmg from GitHub Releases and copies the app to Applications. Then it installs the pensieve backend from the package inside the app. You do not need git, the Xcode tools or Python.
• On Linux and Intel Macs: it installs uv if it is not there. Then it installs the backend from source with git, starts the backend and opens the Map at http://localhost:8765.
• The pensieve command goes in ~/.local/bin.

Two environment variables change the script. PENSIEVE_NO_START=1 never starts Pensieve. PENSIEVE_NO_APP=1 skips the Mac app.

What pensieve integrate recommended does

The command finds the agents on your computer. It gives each one Pensieve as an MCP server, a short “search before you grep” instructions block, and the pensieve-search skill. For Claude Code, it also adds three hooks. Connect your agent lists each change, file by file.

Choose what to index

Pensieve indexes nothing until you finish setup. This is also true after a reset. When the app opens, it shows these steps:

1. Read what Pensieve does.
2. Choose how you use your computer: software development, AI coding agents, documents and office work, or research and notes.
3. Let Pensieve look for sources in the folders that those choices need. macOS can ask you to allow access to some folders.
4. Choose what to index. Add folders or repos that Pensieve did not find.
5. Choose whether Pensieve reads images, video and audio by what they show or say. These are off by default.
6. Choose the search model.
7. Start indexing.

To do setup from a terminal, use these commands:

pensieve setup                  # list the sources that Pensieve found, with their sizes
pensieve setup recommended      # index the sources marked [x]
pensieve setup recommended images audio   # also read images and sound by content

An agent can also do setup in its chat. Until setup is done, every MCP connection gets the tools setup_guide, setup_scan, setup_add_source and setup_start.

The first index

The first index uses a lot of energy. The search model runs until it finishes, at 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. Settings → Sources shows what is syncing now.

Install by hand

uv tool install git+https://github.com/TedHaley/pensieve   # the backend: `pensieve`
git clone https://github.com/TedHaley/pensieve && pensieve/mac/build.sh --install   # the Mac app (needs the Xcode tools)

Update

The Mac app finds new releases on GitHub and installs them. You can also run the install script again.

Uninstall

1. Remove what pensieve integrate added. Name each add-on that you installed:

   pensieve integrate claude claude-mcp claude-hook --remove

2. Remove the backend, the index and the app:

   rm -rf ~/.local/share/uv/tools/pensieve ~/.local/bin/pensieve ~/.pensieve ~/Applications/Pensieve.app

If the app is in /Applications, remove it from there.

Something wrong or missing? Tell us on GitHub.