Independent AI intelligence Two editions daily · ET
Fervor AI
Menu

Analysis · October 12, 2026 · repo

PensieveTedHaley/pensieveclaude-codecodexmcplocal-aiagent-memory

Pensieve Turns Your Coding Agent's Grep Loop Into One Search

A local MCP index cut agent tool calls by 43% in its own test. What it indexes by default, when grep still wins, and how to set it up narrow.

Watch a coding agent look for something in a big repo and you will see the same dance every time. It greps for a word. It opens a whole file to check the match. It greps again with a better guess. It opens another file. Each step is a round trip that you pay for in tokens and seconds, and on a large codebase the agent can spend more effort finding the code than changing it.

The odd part is that the agent is searching the way people searched before code search existed. It has no memory of where things live, so it rediscovers the map on every task.

Pensieve, a free, open-source Mac app that hit Hacker News over the weekend, tries to give agents that map. It builds a local index of your code, files and past agent sessions, then answers an agent's question in one search that returns the relevant passages with file paths and line numbers. Its own benchmark says that cut tool calls per lookup by 43% and cost by 18%.

That number is real enough to be worth testing. The defaults are broad enough to be worth reading first.

What Pensieve actually does

Think of the difference between asking a librarian and walking the shelves.

Grep walks the shelves. It is fast and exact, and it finds a string only if you already know the string. An index works like the librarian: it has already read everything, so you can ask by meaning ("where do we retry failed payments?") and get pointed at the right shelf.

Pensieve builds that index on your Mac. It turns code and documents into embeddings (numeric fingerprints of meaning, so similar ideas sit near each other) and also keeps exact-word search. Then it exposes the index to agents over MCP, the Model Context Protocol, which is the standard way tools like Claude Code and Codex plug into outside services. Once it is connected, the agent gets new tools such as search, read and similar, and can call search before it ever reaches for grep.

The README lists what goes into the index by default:

  • Agent sessions: transcripts from Claude Code, Codex and Qwen Code.
  • Files and folders: ~/Documents, ~/Desktop and ~/Downloads, including Office files, PDFs and mail.
  • Git repositories: repos your agents used, plus repos found under your home folder up to four levels deep, uncommitted changes included.
  • Obsidian vaults: on by default. Apple Notes is off by default.

The index, settings and everything else Pensieve stores live in ~/.pensieve (the app and command line tool install elsewhere). Searches come back in about 0.1 to 0.2 seconds.

The session index is the clever part. An agent can search what it, or another agent, already figured out last week, instead of rediscovering it.

What the benchmark says, and whose numbers they are

These are the project's own measurements, run by its author, so read them as a strong claim rather than a settled fact.

The test ran Claude Sonnet through Claude Code in headless mode (scripted, with no human at the keyboard) on 72 code-finding tasks across four repos, from 504 files to 34,847 files. There were two setups, one with only grep, glob and file reads and one with Pensieve plus instructions to use it, and each task ran twice in each, for 144 runs per setup. The tasks were held out, meaning they were not used to tune Pensieve. The README reports, on version 0.5.6:

  • Right file found: 131 of 144 runs with Pensieve, 123 of 144 without.
  • Tool calls per lookup: 1.97 versus 3.44, about 43% fewer.
  • Cost per lookup: $0.041 versus $0.050, about 18% cheaper.
  • Tokens per lookup: about 57k versus 67k.
  • Time per lookup: 8.6 seconds versus 10.9.

Two caveats come from the README itself. Costs depend on how warm the prompt cache was (text the API has recently seen is billed cheaper), so the author says to compare them only within one batch. And the savings vary: the project page reports Pensieve was cheaper in all four repos, while the README's per-repo breakdown runs from about 6% to 28%, with the biggest cut on the 34,847-file repo.

The more honest result is the one most launch pages would bury. In single-search tests, grep beat Pensieve on exact error strings, 92% to 88%. If your agent is hunting for ECONNRESET or a stack-trace line, grep is still the right tool. Pensieve wins when the agent knows what the code does but not what it is called: on description-only queries, its first result hit the right file 58% of the time, where a single grep scored 0%.

So the takeaway is narrower and more useful than "index beats grep." An index beats grep at questions grep can't ask.

The defaults deserve a second look

Reading the README this morning, the line that stopped me was the default folder list. A tool sold as a faster way for agents to search code indexes your Documents, Desktop and Downloads folders out of the box, along with git repos it finds up to four folder levels under your home directory. (Auto-discovered repos with more than 5,000 tracked files are skipped by default, per the max_repo_files setting in settings.py.)

That is a reasonable default for a personal search app. It is a broad one for something you then hand to an agent.

Three details matter here:

  1. Secret filtering works on file names. The README says files that look like secrets, such as keys, .env files and credentials, "are never indexed," using filename patterns in the exclude_files setting. That catches .env. It can't recognize an API key pasted into a meeting note or an agent transcript, because by name those are ordinary files.
  2. "AI insights" can leave your machine. Search runs locally, but if you choose Claude Code or Codex as the engine for Pensieve's insight features, it sends text to Anthropic or OpenAI. A built-in Qwen 3.5 9B model, LM Studio or any OpenAI-compatible local server keeps it on the Mac, or you can switch insights off.
  3. Scopes are the safety valve. Each agent connection works within a scope, which the README describes as "a slice of the index, such as the repo it's working in." Named scopes are just lists of sources, so you can give one project's agent only that project.

None of this is a flaw so much as a setup decision Pensieve makes for you unless you make it first.

Put this into practice

Here is the narrow setup: index the repo you care about, connect one agent, and measure before you trust it.

1. Install. On an Apple Silicon Mac:

curl -fsSL https://tedhaley.ca/pensieve/install.sh | sh

This installs the app and the pensieve command line tool. Intel Macs and Linux get a source install through uv (a fast Python package manager) instead. Expect a model download of about 1.2 GB for the embeddings, and about 5 GB more if you turn on the built-in AI model, which the README lists at 16 GB of memory.

2. Trim the sources before the first index finishes. Open Sources in the app and switch off Documents, Desktop and Downloads unless you want them searchable. The README notes that switching a source off also removes what it had indexed. If your project has more than 5,000 tracked files, add it as a source yourself, because auto-discovery skips repos that big. Then make a named scope in Settings → Scopes that contains only your project.

3. Connect Claude Code to that scope. Skip pensieve integrate recommended, which wires up every agent it detects, and connect one agent by hand:

claude mcp add pensieve -- pensieve mcp --scope myproject

Replace myproject with your scope's name. Run it inside the project folder so the server only applies there. (Adding --scope user after mcp add would make it available in every project, which is the opposite of narrow.)

4. Wait for the first index. On Apple Silicon the README estimates about 500 code files a minute, so a 35,000-file repo takes a little over an hour. Search works while indexing runs.

5. Measure on your own code. The benchmark scripts ship in the repo's bench/ folder. Clone the repo and run bench/agent_search.py gen against your codebase to generate tasks, then run with the grep and guided arms (the two setups) to compare. The README has the exact commands. Your repo, your model and your cache state will give you a different number than 43%, and that number is the one that matters.

To undo it: pensieve integrate claude --remove removes exactly what the integration added, and deleting ~/.pensieve clears the index.

Honest limitations

It is young and small. Fewer than 30 GitHub stars as of October 12, an MIT license, an author-run benchmark on one model, and fast-moving versions: the benchmark used 0.5.6, the project page lists 0.5.9, and a v0.6.3 release appeared on October 12. Re-run the test after upgrades.

It is Mac-first. The one-line app install needs Apple Silicon and macOS 14 or later. Other platforms get the backend from source.

The first index is slow on big repos, and you pay that hour again if you wipe ~/.pensieve to start over.

Big documents get cut off. By default Pensieve skips files over 20 MB and reads only the first 2,000 pieces of each document, so text past that point is not searchable until you raise max_chunks.

The headline numbers are averages over four repos. Per repo, the cost savings ranged from about 6% to 28%, so your own codebase could land anywhere in that range, or outside it.

More tools can mean more confusion. The benchmark setup that won used Pensieve plus instructions telling the agent when to search. Plugging in the server without those instructions is a different experiment.

Where this leaves you

Agents waste a surprising amount of money rediscovering where code lives. Pensieve is one of the first tools to publish a reproducible test of the fix and to admit in the same breath where grep still wins.

Give it one repo and one agent for a week, scoped tight, and run the bench on your own code. If the number holds up, widen it. If it doesn't, you've lost an hour of indexing and learned something real about how your agent searches.

Sources: Pensieve project page, TedHaley/pensieve README (main branch, read October 12, 2026; benchmark figures are the author's own, on version 0.5.6), Hacker News discussion.

Medium metadata

Title: Pensieve Turns Your Coding Agent's Grep Loop Into One Search

Alternates to test:

  • You Don't Have to Make Coding Agents Rediscover Your Code Anymore
  • Your Coding Agent Doesn't Have to Grep Its Way Through Every Repo Anymore

Subtitle options:

  • A local MCP index cut agent tool calls by 43% in its own test. What it indexes by default, when grep still wins, and how to set it up narrow. (picked)
  • One search instead of a grep-and-read crawl, with the defaults you should change first
  • What a local code index saves your agent, and the one place grep still wins

Description: Pensieve indexes your repos and agent sessions so Claude Code finds code in one MCP search. Its benchmark, its broad defaults, and a narrow setup.

Tags (priority order):

  1. Claude Code: the agent the benchmark and setup commands target.
  2. MCP: how Pensieve plugs into agents.
  3. AI Agents: the broad audience.
  4. Developer Tools: practical install-and-try piece.
  5. Software Development: widens reach to working developers.

Article type: A (spike: a real repo and release with a measurable payoff). Publish plan: post at 7 to 8 AM, let Medium distribute for 2 to 6 hours, send to subscribers only if it is performing.