Skip to main content
Glama
Sign In
JSkier21

notesearch-mcp

by JSkier21
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

notesearch-rag

Hybrid search over a folder of markdown notes (for example Claude Code's auto-memory), as a command line tool and as an MCP server for Claude Code, LM Studio and any other MCP client.

It follows the "raw-history RAG" idea from Is Complex Agentic Memory Always Needed? Naive RAG Is Stronger Than We Thought (code: Litmeb/RAW-RAG): keep the original text, retrieve relevant windows, let the reader model do the reasoning. This is an independent, much smaller implementation and shares no code with that repository.

  • Notes are cut into overlapping raw-text windows (about 1500 characters), each prefixed with the note's name and description. Nothing is summarised.

  • Retrieval fuses dense vectors (any OpenAI-compatible /v1/embeddings server, default LM Studio with bge-m3) with BM25 keyword search by reciprocal rank fusion. BM25 keeps IPs, hostnames and flags as whole tokens as well as their parts.

  • The index refreshes itself: only windows whose text changed are re-embedded. If the embedding server is down it falls back to keyword-only search and says so.

  • Runtime dependencies: Python, numpy, requests. No GPU or torch needed.

Use

notesearch --update                 # build/refresh the index once
notesearch "why does the printer web page time out"
notesearch -n 3 -v --json "dhcp reservation"

Related MCP server: Notes RAG MCP Server

MCP server

notesearch-mcp speaks MCP over stdio and provides two read-only tools: search_notes and read_note. Build the index once with notesearch --update first.

Claude Code:

claude mcp add --scope user notesearch -- notesearch-mcp

LM Studio (~/.lmstudio/mcp.json):

{ "mcpServers": { "notesearch": { "command": "notesearch-mcp" } } }

Configuration (environment variables)

Variable

Default

NOTESEARCH_NOTES

~/.claude/projects/<home path with / as ->/memory

NOTESEARCH_DATA

$XDG_DATA_HOME/notesearch (the index)

NOTESEARCH_EMBED_URL

http://127.0.0.1:1234/v1/embeddings

NOTESEARCH_EMBED_MODEL

text-embedding-bge-m3-latest

NOTESEARCH_EMBED_KEY

empty (optional bearer token)

NOTESEARCH_SKIP

MEMORY.md (comma-separated file names to leave out)

Changing the embedding model rebuilds the index automatically.

How well does it work?

On a private collection of about 440 notes, with 25 self-written paraphrased questions, the right note was in the top 5 for 92% of questions with hybrid search, against 40% for a grep-style search and 68% for BM25 alone. A cross-encoder reranker added nothing at 13 s per query on CPU, so it is not included. The questions were written by the author and are optimistic; treat this as a rough comparison, not a benchmark. Retrieved notes can be stale, so verify before acting on them.

Tests

PYTHONPATH=src python -m unittest discover -s tests

License

MIT

Available Tools

2 tools
read_noteA
Read-only

Return the full text of one memory note by file name, e.g. 'opnsense-dhcp-kea.md'.

NameRequiredDescriptionDefault
nameYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the whole document is returned rather than a snippet, but says nothing about behavior for a missing note or whether the extension is required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the verb and return value, with the input format demonstrated inline rather than described abstractly. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the key facts (full text returned, keyed by file name) are present. The main gap is error behavior when the note does not exist, a small omission given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% — the single 'name' parameter has no description at all — so the description carries the burden and does so: 'by file name' plus the concrete example 'opnsense-dhcp-kea.md' communicates the expected format, including the .md extension.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Return the full text of one memory note by file name.' The singular 'one note' and the file-name keying implicitly contrast with search_notes, but the sibling is never named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'by file name' — the agent infers this is for fetching a known note rather than discovering them. There is no explicit statement of when to use this versus search_notes or what to do if the file name is unknown.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_notesA
Read-only

Search the user's long-term memory notes (markdown) by meaning and keywords. Returns the best-matching notes with a description and passage. Notes can be stale: verify before acting on them. Use read_note to open a whole note.

NameRequiredDescriptionDefault
nNoHow many notes to return (default 5, max 15)
queryYesA question or keywords, in plain language

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish that this is a read-only operation. The description adds useful behavioral context beyond the annotations: it explains that results include a description and passage, and warns that notes can be stale and should be verified before use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the core action, and every sentence contributes: search behavior, return shape, staleness warning, and sibling routing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with full schema coverage and annotations, the description covers the essential gaps: it explains what is returned, warns about stale content, and points to read_note for full-note access.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully documents both parameters, including the default and maximum for n and the plain-language query format. The description reinforces the search mode by mentioning meaning and keywords, but adds no parameter-specific semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: searching long-term memory notes by meaning and keywords. It also clearly distinguishes the tool from the sibling read_note by explaining that read_note is for opening a whole note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage direction by naming read_note as the alternative for opening a whole note and warning that notes may be stale and should be verified before acting. It does not explicitly state when not to use search_notes, but the sibling routing is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedread_note
    • First observedsearch_notes
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are complementary and non-overlapping: search_notes locates notes by meaning/keyword, and read_note opens one specific note by filename. Descriptions explicitly state the handoff between them (search first, then read the whole note).

Naming Consistency5/5

Both names follow the same verb_noun snake_case convention (search_notes, read_note). The pattern is predictable and self-documenting.

Tool Count3/5

Two tools is on the thin side for even a narrow server. It covers the search-and-open flow, but there is no room for supporting operations like listing or browsing notes.

Completeness3/5

Retrieval is covered end-to-end (find then read), but the memory domain has a notable gap: there is no way to create, update, or list notes, so an agent cannot persist or enumerate memories. It is workable if notes are written by other means, but the surface feels partial.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • secondbrain-mcp

    qingleiw
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to list, search, read, and append to Markdown notes through MCP tool calls, making it easy to interact with a second brain folder.
    -

  • second-brain-mcp

    nanthansr
    A
    license
    A
    quality
    C
    maintenance
    Enables MCP clients to search and read notes from an Obsidian or markdown vault through four governed tools, with enforced read-only access, a page budget, and path sandboxing.
    4
    8 npm
    1
    MIT

  • Brain MCP

    Artur0927
    A
    license
    B
    quality
    C
    maintenance
    Enables hybrid dense and BM25 search over a markdown vault, with tools for reading, writing, grepping, and managing notes through any MCP-compatible client.
    12
    MIT