Edith Second Brain README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Edith Second Brain listing page.
Edith Second Brain
A second brain for AI.
edithapp.ai · Download for macOS · VS Code extension
Edith is a local, plain-Markdown knowledge base that Claude can read from and write to. Ask Claude to review your past sessions and it distils them into linked notes itself - no API key, no account, no inference of its own.
What it does
- No API key. No account. No inference. Claude reads and writes your notes through its own session, on the plan you already pay for. Edith is the store and the canvas.
- Claude fills it for you. Ask "review my recent sessions and save anything worth keeping" and Claude reads your transcripts with
list_sessions/read_session, then writes the notes back withsave_note. - Serves Claude over MCP.
search_brain,read_note,list_notes, andsave_note. Claude both reads from and writes to the brain mid-session. - Shows you the retrieval. A search dims-glows what Claude considered; opening a note brightly glows what it actually used. Highlights fade over 30 seconds.
- Mini mode beside your session. Minimize Edith and it becomes a narrow panel docked to the left edge of the screen, drawing your brain and lighting up the notes Claude reaches for - the window and the panel are never up at the same time. With the window closed or minimized, the panel also opens on its own when a Claude session starts. It never takes focus, folds to a strip the width of the rail or shrinks to a small square in the corner - both just the live graph - and stays closed for the rest of a session once you close it. Turn off the automatic opening under Connection.
- Takes your own content too. Add content imports
.md,.markdown,.txt, and.mdxfiles, or anything you paste. Files keep their existing frontmatter, so importing a Markdown vault preserves ids and links instead of duplicating notes. Import as written, or distil into concepts. - Plain Markdown. Files on disk are the source of truth. Edit them in any editor. Delete the index and it rebuilds.
Install
Edith runs on a Mac with Apple Silicon, macOS 13 or later. You also need Claude Code, in the terminal or the VS Code extension.
Download Edith — signed and
notarised by Apple, so it opens with no security warnings. Open the .dmg, drag Edith into
Applications, and open it from there. Restart any Claude Code sessions that were already running.
On Windows? The Windows build lives at Edith-Windows.
In VS Code
The Edith extension
registers Edith as an MCP server in the editor, so there is no mcp.json to write and no port to
look up:
It finds the running app and hands the editor a live connection. If Edith is not running when the
editor goes to start the server, the extension offers to open it. The source is in
vscode-extension/.
Edith is also listed in the official MCP registry as io.github.Rchari1/edith-second-brain, so
clients that read the registry can find it without any of this.
Or build it yourself
Needs Node.js 22.12 or newer, and the Xcode command line tools
(xcode-select --install) for the native database module:
The .dmg lands in release/. A build you make yourself is not notarised, but it opens anyway,
because macOS trusts what you compiled on your own machine.
What happens on first launch
Edith starts its brain server on 127.0.0.1:4319 and connects itself to Claude. There is no account and no API key: ask Claude to "review my recent sessions and save anything worth keeping" and it fills the brain itself.
Outside its own folder, Edith adds:
| What | Where |
|---|---|
| Its server entry, so Claude can reach the brain | ~/.claude.json, plus Claude Desktop's config if you have it |
| A session-start hook that tells Claude the brain exists | ~/.claude/settings.json |
The /edith command | ~/.claude/skills/edith |
| A handful of starter skills | ~/.claude/skills/, managed from the Skills panel |
Your notes are plain Markdown in ~/Library/Application Support/Edith/vault.
Updating
Quit Edith, then drag the new build into Applications to replace the old one.
Troubleshooting
- Edith quits the moment it opens. If you launched it from a VS Code terminal, open it from Applications or the Dock instead - VS Code's terminal sets an environment variable that stops the app from starting.
- Claude never uses the brain. Restart Claude Code after Edith's first launch, then open Connection in Edith and check that the session primer says installed.
Uninstalling
Quit Edith and delete it from Applications. Then remove what it added: the edith entry under mcpServers in ~/.claude.json, the hook in ~/.claude/settings.json whose command ends in # edith:session-context, the ~/.claude/skills/edith folder, and any starter skills you no longer want. Your notes stay in ~/Library/Application Support/Edith until you delete that folder too.
How it works
| Stage | What happens |
|---|---|
| Watch | chokidar on ~/.claude/projects, waiting for a session to go quiet |
| Parse | JSONL to a canonical Session, following leafUuid to skip abandoned branches |
| Store | Markdown + YAML frontmatter, indexed in SQLite FTS5 |
| Serve | In-process MCP server over local HTTP |
| Light up | Every tool call emits an event straight to the renderer |
Tools Claude gets
| Tool | What it does |
|---|---|
search_brain | Search the notes |
read_note | Read one note in full |
list_notes | See what the brain holds |
save_note | Write an insight back |
list_sessions | See past Claude sessions, and which are already captured |
read_session | Read one transcript, tool noise stripped |
The last two are what let Claude do the distilling itself, on your plan, with no key anywhere.
Edith hosts the MCP server itself rather than spawning it. That is what makes the highlighting instant: a tool call and the glow are the same tick.
Adding your own content
Add content in the sidebar opens an import dialog with two modes:
| Mode | What it does | Cost |
|---|---|---|
| Keep as written | Stores the file or text verbatim as a note | free |
| Distil into concepts | Runs the same extraction used on sessions | one API call |
Re-importing a file deepens the existing note rather than creating a duplicate, so syncing a folder repeatedly is safe. A file with broken frontmatter loses its metadata, not its content.
Note format
Every note records the sessions it came from. That provenance is written from day one, so tracing a concept back to its conversations is a view rather than a migration.
Things worth knowing
Upgrading from the old name. Edith was previously called SecondBrain. On first launch it copies your existing vault and settings across from the old location, and replaces the stale secondbrain entry in ~/.claude.json with edith so Claude does not see two identical tool sets. The old directory is left untouched as a fallback.
An API key does not give access to claude.ai history. The Messages API is stateless; there is no endpoint listing past conversations. Edith reads Claude Code's local transcripts. The API key is used only to distill them.
Most .jsonl files under ~/.claude/projects are not sessions. Subagent and workflow transcripts nest under session directories and typically outnumber real sessions by roughly 9:1. Edith classifies by path shape so they never become notes.
Transcripts are trees. Interrupting Claude forks the history and leaves the abandoned branch in the file. The parser walks back from last-prompt.leafUuid so only what actually happened gets distilled.
Your config is safe. Registration merges a single key into ~/.claude.json, writes atomically, and backs the file up before first modification.
Development
Tests cover path classification, fork resolution, malformed-line tolerance, vault merge semantics, config-write safety, a live MCP client over HTTP, and the full pipeline end to end with the API call mocked.
Not in v1
claude.ai export import - session-layer graph rendering - cross-machine sync - semantic search. Search sits behind a SearchProvider interface, so adding hybrid retrieval later touches one file.
License
Edith is source-available under the Functional Source License, Version 1.1, MIT Future License (FSL-1.1-MIT). You can read, use, modify and share it for anything except offering it, or something substantially similar, as a competing commercial product or service. Each release becomes MIT-licensed two years after it is published.
© 2026 Raghav Chari and Kate Bonner.