Yaro

Yaro is a tool for managing your markdown notes. It adds semantic indexing, full-text search, and tools for conceptual exploration (more below). It provides an MCP server to turn your coding agent into a notes assistant. Yaro acts as the navigator for both you and the agent.

There is no app or UI. Edit notes in your favorite editor, and let your agent use Yaro from the command line or MCP.

Features

Plain markdown files: Edit your notes directly or use your agent to do it. Yaro captures and indexes all note changes.

More powerful querying: Yaro combines full-text search, semantic search, wiki links, and tags to find relevant notes from more angles than text search alone. Agents can find the right notes and relevant text with fewer tokens.

Surface hidden connections. Yaro finds threads between notes you didn't know were related, and helps connect them to outside ideas that aren't directly present in your workspace.

Setup

1. Install Yaro
2. Initialize Your Notes Workspace
3. Connect Your Agent
4. Edit Notes

1. Install Yaro

Homebrew

macOS is currently supported through Homebrew:

brew tap dgllghr/yaro
brew install yaro

Build from source

cargo install --path .

2. Initialize Your Notes Workspace

Create or open the directory where your markdown notes live, then run:

yaro init

Yaro creates its database in .yaro/, indexes existing .md files, and writes project MCP config for Claude Code, VS Code, and Codex.

3. Connect Your Agent

Claude Code, VS Code Copilot, and Codex should detect the generated MCP config and prompt to allow it. Your agent will start yaro serve automatically when it needs Yaro.

If you are not using an agent, run yaro serve while editing or yaro save after edits.

Codex

Yaro installs Codex as a project-scoped MCP server in .codex/config.toml. This lets Codex start Yaro only inside this Yaro workspace instead of trying to start it in every project.

If you previously registered Yaro globally, remove the global entry:

codex mcp remove yaro

Then run yaro init or refresh the project config:

yaro mcp install codex

Allow the Yaro MCP server when Codex starts in this workspace.

4. Edit Notes

Create and edit normal markdown files. yaro serve / yaro save will index all files and add frontmatter to them if it is missing. Yaro understands and indexes the title and tags fields. It will also populate indexed note frontmatter with id and created fields.

Conceptual Exploration

Yaro indexes and connects notes in a few ways:

• Semantic embeddings
• Full text search (FTS)
• Wiki-links
• Tags

These indexes power straightforward queries, but together they also enable Yaro’s most distinctive capability: exploration. explore groups notes at query time into a cluster of related material called a plateau. From that plateau, Yaro looks for connections just outside the obvious neighborhood: ideas that are orthogonally, obliquely, or unexpectedly related.

Yaro calls these connections lines of flight. They are bridges across conceptual boundaries: prompts to move from what your notes already say toward what they might imply, connect to, or be missing.

These hidden and unexpected connections are meant to help you escape calcified thinking and endless loops. They open new routes through a workspace, making it easier to ask better questions, notice neglected patterns, and bring outside concepts back into the work.

explore generates a markdown brief for an agent. Given a concept or starting note, it maps the surrounding plateau and surfaces places to go next: lines of flight, implicit concepts, and crossings. The brief acts as navigation context, helping the agent decide which notes to inspect, which connections to follow, and which outside ideas may be worth bringing back into the workspace.

CLI

Yaro is also a CLI tool for humans and agents.

Run commands from the root of a Yaro workspace unless noted otherwise.

Keep The Index Current

Use serve while you are actively editing notes or working with an agent:

yaro serve

In workspace mode, serve watches markdown files, reconciles changes into .yaro/, runs derived indexing tasks, keeps full-text search current, and exposes the MCP server over stdio.

For a one-shot update, use:

yaro save

save reconciles the current files and waits for relevant derived tasks, but it leaves history unsealed. This is the normal command to run after edits when no long-running yaro serve process is watching the workspace.

Use commit when you want to seal a durable boundary:

yaro commit

commit reconciles files, waits for derived tasks, may compact local history, runs cleanup when appropriate, and seals the current commit frontier. It is a human durability command, not the normal post-edit indexing command.

Inspect And Search Notes

List indexed notes:

yaro note list

In workspace mode, each row includes the note id, display title, extracted link count, chunk count, and file path.

Search titles and bodies with Yaro-owned plain search syntax:

yaro search "indirect coordination"

Use advanced syntax only when you need explicit required terms, excluded terms, or phrases:

yaro search --advanced '+coordination -pubsub "shared state"'

Generate a navigation brief for a question, concept, direction, or note:

yaro explore "indirect agent coordination"

explore combines search, nearby context, bridge notes, lines of flight, and implicit concepts into a compact markdown brief. This is the CLI version of the context Yaro gives agents before they answer non-trivial workspace questions. It is designed for agents, but it is readable as a human navigation guide too.

Check And Repair Local State

Show pending workspace changes before saving or committing:

yaro status

Check the local database, materialized notes, tasks, workspace diagnostics, and FTS index health:

yaro doctor

If full-text search reports stale or missing index state, rebuild it:

yaro rebuild fts

Manual maintenance commands are available when you need them:

yaro compact
yaro gc

compact rewrites eligible unsealed local history. gc removes unreferenced CAS bytes after retained history and live task inputs no longer need them.

MCP Setup From The CLI

Install or refresh editor MCP config:

yaro mcp install claude
yaro mcp install vscode
yaro mcp install codex

These commands write project-local configuration. The Codex installer writes .codex/config.toml so Yaro is only launched in the current Yaro workspace.

Run the MCP server directly:

yaro mcp

Most agent workflows should use yaro serve instead, because it runs the MCP server and keeps the workspace indexed while files change.

MCP Tools

When an editor starts yaro serve, it gets read-only tools for exploring the workspace. The assistant still edits markdown files on disk, just like you do.

The Yaro tools let assistants:

• list indexed notes and their file paths;
• explore a concept, question, direction, or note with one navigation brief that combines search, nearby notes, bridge notes, outward research candidates, and underdeveloped concepts;
• gather workspace context before answering non-trivial questions that may depend on existing notes;
• search across note titles and bodies;
• find notes that are closely related to a seed note;
• find crossings: bridge notes that connect one topic area to another;
• find lines of flight: evidence-backed concept launch points for research;
• find implicit concepts: central ideas a topic area is circling but has not developed clearly;
• inspect outgoing [[wiki links]] and possible backlinks;
• find broken wiki links whose targets do not resolve to any note;
• show workspace diagnostics for malformed frontmatter, invalid tags, duplicate ids, and path conflicts.

These tools use Yaro's database and derived indexes, so they can see relationships that plain text search cannot: ambiguous wiki-link resolution, chunks, embeddings, and note-to-note similarity.