Local Code Search for AI Agents: Pensieve ⚡
Discover Pensieve: local code search for AI agents with semantic accuracy via MCP for coding agents—fewer tool calls, lower lookup costs. See benchmarks.
Pensieve Gives AI Coding Agents a Better Way to Find Code
AI coding agents can write code quickly. But figuring out which code to change is a different - and often slower - problem. Ask an agent why a payment retry stops after a decline, and you may watch it bounce between a few keywords, open a handful of files, and then keep digging because the real rule is described in a totally different way. By the time it finds the right evidence, you've already paid in time, context, and API budget.
Pensieve tries to fix that part. It indexes selected files, repositories, and even coding-agent sessions on your Mac, then lets you search across them by meaning or by exact wording. When an agent is connected through the Model Context Protocol (MCP), Pensieve can return relevant passages with file names and line numbers - so the agent doesn't have to "grep the disk" and read whole files just to get oriented. It also maps code ownership and surfaces places where the knowledge is likely thin.
This article walks through how Pensieve works, what its benchmark does (and doesn't) show, and what trade-offs you make when you add local search to an AI development workflow. The real question isn't whether semantic search beats grep in every situation. It's whether the right retrieval method helps your agent reach useful evidence with less wasted work.
Why Code Search Matters for AI Agents
An AI coding agent is only as good as the context it can find - and as the evidence it can interpret correctly. When the relevant logic is scattered across source files, tests, docs, and old incident notes, the agent has to locate that trail before it can make a reliable change.
A common starting point is some variation of grep: search for a term, inspect matches, tweak the query, repeat. That works when you already know the exact identifier or error text. But natural-language questions don't always map cleanly to the names developers chose in the codebase. A question like "why does a card retry stop after a decline?" might involve a hard-decline check, a queue, a gateway response, and a past decision captured in a review. Searching only for "retry" can give you a pile of results - many of them plausible - without telling you which one actually matters.
The cost of broad retrieval
Every extra file the agent opens becomes more noise in its working context. It can also mean more tokens and more tool calls. The cost isn't only the API bill, either: more search steps can slow feedback, increase the odds the agent pursues the wrong lead, and shrink the space it has left to do the actual work inside a limited context window.
This is, at heart, a retrieval problem. A stronger model can't magically reason from evidence it never found. And giving the model a big stack of loosely related files doesn't guarantee better answers either. The goal is to get enough relevant material to act - while keeping the rest out.
Search by meaning and by exact text
Semantic search helps when the question describes a concept but the code uses different wording. Exact search still matters for identifiers, error strings, and known phrases. In practice, you usually want both.
Pensieve supports that mix. You can search with plain language, quote exact phrases, use minus signs to exclude terms, and narrow results by code, files, sessions, file types, or a specific folder/repository. You can start broad, then tighten the search when you know the task needs it.
The practical point is simple: semantic retrieval is great for discovery, while exact matching is often the quickest way to reach a known symbol or message. Most engineering tasks don't need a religion about search - they need the right method for what you already know.
How Pensieve Finds and Delivers Context
Pensieve runs on macOS and indexes what you choose: folders, Git repositories, agent sessions, and (optionally) Apple Notes. The search UI is built for quick use - open a panel over your work with a keyboard shortcut, then act on results without shifting into a separate "research" workflow.
For agents, the bigger piece is the MCP connection. MCP gives an AI client a standard way to call tools provided by another application. With an agent connected to Pensieve, the agent can ask a question and get back selected passages with file paths and line numbers. Instead of requesting a disk-wide search and then opening a lot of files, it can start with a smaller set of likely evidence.
For more on MCP, see the Model Context Protocol documentation. Pensieve supports connections for clients including Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Claude Desktop, and VS Code, with MCP access through standard input/output or HTTP.
Scope the search to the task
A search tool only helps when its results are scoped sensibly. Pensieve can use the repository and worktrees associated with an agent's current project. You can also define a scope that includes specific repositories and folders - like a set of codebases plus a directory where specs live.
This is basically a guardrail against a common failure mode: an agent finds a plausible passage in an unrelated project and treats it as authoritative. Search scope doesn't replace verification, but it reduces the amount of irrelevant material competing for attention.
Pensieve also watches indexed locations and re-indexes changes. Uncommitted edits and Git worktrees are included, with worktrees tracked by branch. That matters in active development: a tool that only reflects the last commit can hand an agent stale context right when a developer is working on a change.
Search is not enough; agents need instructions
It's possible to set up an MCP server correctly and still have it do nothing. Agents have habits, and if they don't know they can call a tool, the tool won't be used. Pensieve's recommended integration adds a "search before you grep" instruction for supported agents, plus a search skill and optional hooks for Claude Code.
It's a small product choice, but it's an important one. Tool availability and tool adoption are different problems. When you evaluate the integration, don't just confirm the connection works - check whether the agent actually selects it on real tasks. Also restart agents that were already open during setup, since some won't load newly configured MCP servers until you start them again.
What the Benchmark Tells Us
Pensieve's published benchmark compares Claude Sonnet in Claude Code with and without Pensieve on held-out code-finding tasks. The tasks use four real repositories (from 504 to 34,847 files). They include questions phrased in different ways - descriptive prompts, exact names, and error messages. The benchmark scripts are in the project's repository, so teams can inspect the approach and run similar tests on their own code.
In the reported results, there are 72 tasks per setup, run twice (144 runs total). Pensieve is used alongside the default agent tools plus an integration instruction block. Across the runs, the agent finds the correct file in 131 of 144 runs with Pensieve, versus 123 of 144 using grep alone. It also averages 2.0 tool calls per lookup with Pensieve, compared with 3.4 with grep, and the source reports that 82 of 144 Pensieve runs answered after a single call.
Read the results in context
The project also reports lower lookup costs in each of the four repositories, with an overall reduction of 18% and savings of 6-28% by repository. It reports 16% fewer tokens and a 21% faster lookup. Search time itself is reported as 0.1-0.2 seconds. These numbers are for this benchmark, not a guarantee that every codebase, agent, model, and task will behave the same way.
There are also important limitations behind the headline. The benchmark measures whether the agent finds the target file, not whether it makes a correct change or produces a better end result. The cost estimates are based on Claude Code's reported API costs at list prices, and the source notes that prompt-cache behavior can affect cost. Finally, the tasks were held out from tuning, which is good - but a small set of repositories can't represent every organization's architecture or search patterns.
And "grep" isn't obsolete here. The source notes that a single grep is better for exact error messages, while Pensieve does better on other task types. That trade-off is expected: exact matching wins when you know what string to search for; semantic retrieval helps when the question and the code don't share the same wording.
For a team considering the tool, the right test is local. Pull a set of questions from recent engineering work, include both exact-symbol queries and conceptual ones, and compare things like number of searches, files opened, time to useful evidence, and the quality of the eventual answer. The benchmark is a reason to test Pensieve - it's not a replacement for testing it against your own repositories.
Privacy, Ownership and Operational Trade-Offs
Pensieve is designed as a local-first tool. Indexing and search run on your Mac, using an on-device embedding model and a local index stored under ~/.pensieve. The local server is described as answering only that Mac rather than exposing the index to the network or other websites. No account or cloud service is required for the core indexing and search.
You choose which folders, repositories, agents, and apps get indexed, and you can switch individual sources off. Turning a source off removes its indexed content. The project says credentials, keys, .env files, and password-manager exports are skipped. Those steps reduce risk, but they don't replace a normal security review. If you're indexing sensitive company material, you should verify exclusions, access controls, and how the data is handled before you roll it out.
Optional AI features change the data flow
Search, MCP context, ownership information, and knowledge-gap analysis don't require an AI model. Optional summaries and insights can use a built-in model, a local service like LM Studio, or options like Claude Code or Codex - or you can leave those disabled. If you select a cloud model, the project labels the insights as cloud-based. Local indexing doesn't automatically mean every optional feature stays local.
Pensieve may also download models and can check GitHub for updates; the source says update checks can be turned off. If your organization has strict data residency or procurement rules, review the actual configuration and network behavior instead of relying on the general "local" label.
Code ownership is useful evidence, not a complete map
Pensieve uses Git blame and recent commit history to show who contributed code to different areas, who's been active lately, and where knowledge may be concentrated in people who are no longer active there. This can help flag potential bus-factor risk before a migration or incident turns it into an emergency.
But Git history isn't a perfect proxy for expertise. A developer may understand a subsystem deeply without owning many surviving lines, and a large historical contribution doesn't guarantee current operational knowledge. Treat ownership results as a starting point for a conversation, not a definitive ranking of teammates. The value is in making gaps visible early enough that you can verify them and plan a handover.
Indexing also has an operational cost. Initial indexing can use a noticeable amount of energy, and the project recommends plugging in while it runs. The app currently requires Apple Silicon for the full macOS experience. The source describes backend and browser-visualizer options for Linux and Intel Macs, and the search panel on Intel Macs requires Xcode command-line tools. Check the current installation guidance for platform-specific requirements before adopting it.
How to Evaluate Pensieve for Your Workflow
Pensieve is free and open source under the MIT license. The setup flow is designed to start from a supported coding agent, which can install the app, connect available agents, and ask which sources to index. Pay attention to the setup prompt and your source selection rather than approving indexing blindly.
A small evaluation can still be meaningful:
- Pick a bounded repository. Start with a codebase where you can verify search results and where your agent already does repeated discovery work.
- Write representative questions. Mix conceptual questions, exact identifiers, error messages, and questions that require connecting code to docs or prior discussions.
- Compare the same tasks. Run the same set through your current workflow and with Pensieve, keeping the agent, model, and wording as consistent as possible.
- Measure useful outcomes. Track whether the correct file shows up early, how many tool calls and files are needed, total latency, token/API cost, and whether the answer is grounded in the right evidence.
- Review privacy and maintenance. Confirm indexed sources, exclusions, any optional cloud features, update behavior, and what happens when a source is disabled.
This kind of test separates a good demo from something that helps repeatedly. If your team mostly searches for exact symbols in small repositories, grep might already be enough. If developers often ask broad questions across code, docs, and prior sessions - and agents waste time opening the wrong files - semantic retrieval may be a more worthwhile upgrade.
You can learn more from the Pensieve project page. The key decision isn't whether to replace every existing search tool. It's whether adding a focused retrieval layer consistently reduces the cost of finding trustworthy context, without introducing privacy or maintenance issues that outweigh the benefit.
Conclusion
AI agents don't need more context by default. They need the right context, found with as little wasted work as possible. Pensieve combines local semantic and exact search with MCP integration, repository-aware scope, and Git-based ownership signals to address that retrieval problem.
Its published benchmark is encouraging - especially on tasks where the answer isn't discoverable through one clean grep. But it's not proof that every team will save the same amount of time or money, and ownership signals should be treated as clues rather than ground truth. Start with a small, measurable trial, verify privacy settings, and compare it against the search workflow your developers already trust. If it consistently gets agents to the right evidence sooner, it's worth keeping. If not, a simpler tool may be the better system.