Disclaimer
- Open source: Yes, MIT licensed.
- Completely free: Echo itself is free, with no subscription. The local keyword-search workflow below needs no embedding service. Optional semantic search uses a separately configured embedding provider, which may charge; your agent/client may also have its own costs.
- Made with AI beyond the author’s ability to comprehend how it works: No. I understand how the project works and can explain and maintain it.
Finding passages from a vault with Echo
I’m building Echo, an MCP server for personal Markdown notes. It lets an external AI agent retrieve original passages, file paths, headings, and line ranges from a folder of notes, including an Obsidian vault. The agent can then inspect the surrounding text and cite the source in its answer.
For example, while reviewing technical notes, you might ask: “What trade-offs did I record when choosing a caching strategy?” Echo searches the notes; the agent handles the explanation. Echo runs alongside your agent, not inside Obsidian, and does not add a chat panel to the app.
A small local example
Requirements: Node.js >=24.15.0 <25. Windows x64 and Linux x64 have been verified.
Start with a small copy of some notes. Sync adds an echo_id property to Markdown files that do not already have one.
- Make a separate folder for Echo’s configuration and index, outside your vault. From that folder, run:
npm install -g @huanf/echo
echo-mcp init
- Set
config/sources.jsonto the folder of notes you want to search. Replace the example path with your own:
{
"collections": [
{
"id": "notes",
"root": "D:/Notes/Vault-Test",
"include": ["**/*.md"]
}
]
}
-
For this local keyword-only example, change
modeto"bm25"in the generatedconfig/retrieval/balanced.json, keeping the other fields. This disables semantic retrieval and requires no embedding API key. -
In that same configuration folder, index the notes and try a phrase that occurs in them:
echo-mcp sync
echo-mcp search --query "cache invalidation"
- To make it available to an MCP-compatible agent, configure the client to launch
echo-mcpwith these arguments:
serve --config <absolute-path-to-echo.config.json>
The client then exposes echo_search and echo_status. If the client cannot resolve the command on Windows, the setup guide explains how to use the installed Node and CLI paths. The CLI example above also works without connecting an agent.
After changing your notes in Obsidian, run echo-mcp sync again. Echo’s index is stored in SQLite; no separate database server is needed.
Optional semantic search
The default hybrid mode combines keyword and vector search. Enabling it requires an embedding service URL, model, dimensions, and API key. Indexed text and search queries are sent to that provider. The keyword-only example above does not demonstrate semantic retrieval.
I’d appreciate feedback from people who already use an agent alongside their vault: does retrieving specific passages help you revisit your notes, and where does setup or retrieval get in the way?