Docs
Pensieve documentation
This page tells you what Pensieve is, what its parts do, and where to start.
Pensieve keeps the context of your work in one place on your Mac. It indexes your files, git repos, AI agent sessions, tickets and messages. You search it from a panel. Your coding agents search it over MCP. Each person's context is different, so Pensieve builds it from your own work and keeps it on your Mac.
Pensieve is free and open source under the MIT license. It is for developers and their AI agents.
The main parts
Threads
Pensieve makes one thread for each goal of your work. A thread joins the agent sessions, the branch, the PRs, the tickets and the messages of that goal. It says the problem, the goal, the state and what is next. It also gives the steps left to close it, and the command that resumes the last agent session. Each thread has one of five states: To do, Open, Loose ends, Complete or Forgotten. You can share a thread as one HTML file. Read about threads.
MCP server
Pensieve is an MCP server. Your coding agent asks it one question and gets the few files and lines that match. Each hit shows the path, the line, the enclosing definition and the line that matched. Each agent connection works in a scope. By default, the scope is the repo that the agent started in. Connect your agent, or read the MCP tools reference.
Search
Search finds items by meaning and by exact words. It blends a vector search with a full-text search. Then it gives more weight to exact text and to names that a file defines. A search takes about 0.1 to 0.2 seconds. On a Mac, press Control+Shift to open the search panel.
| Query | Finds |
|---|---|
pricing model | Items about that subject, by meaning |
"rate limit" | Items that contain those exact words (case-insensitive) |
-draft | Leaves out items with that word |
kind:code | Code only. Also kind:doc, kind:session, kind:folder, kind:repo, kind:person |
by:sam terraform | Only what that person wrote (code by git blame, documents by author) |
ext:pdf | One file type |
in:my-app | The path or the repo contains this text |
since:3d, until:2026-10-01 | Only what changed in that time: a session by its last activity, code by its last commit, a file by its last change. Use a date, a time back (12h, 3d, 2w, 1m), today or yesterday. until: includes that day. |
project:my-app | Agent sessions of that project only |
kind:session since:yesterday | With no other words: the sessions that match, newest first |
Who knows what
Pensieve reads git blame for each indexed repo. Ask about a subject, not a file, and it names the people who
wrote the most related code. Agents get the same data from the people tool.
Knowledge gaps
A knowledge gap is an area of a repo that people who are no longer active wrote most of. For each area, Pensieve shows who wrote it, which active person knows it best, and its bus factor. The bus factor is the number of active people who hold 10% or more of the lines. By default, a person with no commit in 180 days is not active.
Connections
Connections collect your tickets, threads and pages from MCP servers such as Jira, Slack and Linear. Pensieve calls only read-only tools. Each connection is off until you switch it on. Read about connections.
What Pensieve indexes
You choose each source at setup. You can change your choice in Settings → Sources.
- AI agent sessions: Claude Code, Codex and Qwen Code transcripts.
- Files and folders: documents in
~/Documents,~/Desktop,~/Downloadsand the folders that you add. - Git repositories: committed, staged, modified and untracked files, and linked worktrees.
- Apps: Obsidian vaults and, with your permission, Apple Notes.
- Connections: items from MCP servers. Each one is off by default.
Pensieve never indexes files that look like secrets, such as .env files, keys and credentials.
Models
Pensieve runs one model: the search model. It turns text into vectors, and it always runs on your computer. The default for a new index is EmbeddingGemma 2.
Thread notes, summaries and insights are written in the background. Setup asks what writes them: a command-line agent (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 or Ollama. The built-in model runs only when there is work, and only one copy runs. Search, agent context, ownership and knowledge gaps need none of them.
Something wrong or missing? Tell us on GitHub.