What can you do with this server?

This server exposes read-only tools for searching and exploring a person's Markdown notes index. * Search notes (search_notes): run plain-word queries and get a short ranked list with note path, heading, date, snippet, and match reason; limit up to 20. * Open a result (open_result): retrieve the full matched section, or the whole note if short, by result id. * See surrounding context (around_result): view sections before and after a result, plus other notes written that day. * Check index health (check_index): report whether the index is fresh, whether anything private slipped in, and whether searches are fast. * It cannot write, move, or delete notes; locked private notes can be found but not opened by the agent.

Which integrations are available for this server?

Provides local, read-only search over a folder of Markdown notes, returning ranked sections with source details such as note, heading, and date so an agent can find relevant note content quickly.

Phygital Engram

Official

by Phygital-Brain

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

NOTE

Works with any folder of Markdown notes, and is made to sit besidePhygital Brain. It is not related to other projects that happen to be called Engram.

What it is

Phygital Engram is a search for a folder of Markdown notes. Your agent asks it a question, and it returns a short list of the best matches. Each one shows the note, the heading and the date, so you can see where an answer came from.

It only reads your notes. It never writes, moves or deletes one. Its own files live somewhere else, and you can delete them whenever you like.

You:   When is the cover due?
Agent: Searching your notes. 3 results, about 11 ms.
       The cover is due on the 15th. Marta moved it on 20 October.
       Source: Projects/Picture-Book > Schedule, 2026-10-20.

You:   And what did we agree on the call?
Agent: The Penguin Kids call note says the print files follow a week later.
       Source: Relationships/Clients > Calls, 2026-10-19.

Related MCP server: second-brain-mcp

Why it exists

Once your notes grow past a few hundred files, your agent has bad choices. It can read everything, which is slow and can cost more than it can hold. Or it can guess which files to open, and miss the one that matters.

Pasting everything in does not work either. The AI treats an old note and a new one as equally true, and the more text it reads, the worse and slower its answers get.

Phygital Engram adds a better choice, a search that knows your notes. It ranks by your words, and also by where a note lives (a rules file counts more than an old archive), how new it is, and whether it is marked done. The right note comes up first more often, and the answer is short to read.

Without it	With Phygital Engram
Your agent reads hundreds of files to answer one question	It reads a short list, about 1,100 tokens in the author's tests
A note from last year ranks the same as today's	Newer notes count more, rule notes never fade
An old archive note beats the current one	Archives and finished notes sink a little
You can't tell where an answer came from	Every result names its note, heading and date
Search sends your notes to a service	Everything stays on your computer

Safety and privacy

WARNING

The index is made from your notes, so treat it like your notes. It sits in a folder on your computer, and anyone who can read that folder can read what it holds. Readdocs/safety.md before you point it at private folders.

Your notes are read-only. It never writes, moves or deletes a note. It refuses to start if its own folder would sit inside your notes folder.
Secrets are blanked before storing. Lines like PASSWORD=, TOKEN= and API keys become [REDACTED]. Labelled tax IDs, IBANs and card numbers are blanked too.
Password files are never read. .env files, key files and credentials.json are skipped.
Private folders are locked. A finance folder can be findable but locked: a match shows only the file name and heading, and the text opens only when you ask.
Results are labelled as information. The text your agent receives is marked as note content, never as instructions.
Nothing is collected. No account, no tracking, no calls to us. The only outside call is the optional note cards, which use your own AI key and only if you turn them on.
You can delete the index any time. It rebuilds from your notes in about 15 seconds for 5,000 notes.
Hidden means hidden. Notes marked engram: skip, notes in .claudeignore and hidden folders like .obsidian and .git are never indexed.

More in docs/safety.md and docs/privacy.md.

How it works, in one picture

Phygital Engram builds a small index of your notes, then ranks the matches for each question.

More in docs/how-it-works.md and docs/search-ranking.md.

Words you'll see

Word	What it means here
Note	One Markdown file.
Section	A piece of a note, cut at its headings. Search returns sections.
Index	The small file Phygital Engram builds from your notes so it can search fast. It lives outside your notes.
Source	Where an answer came from: the note, the heading and the date.
Ranking	The order of the results. Words, folder, status and age all count.
Card	An optional summary an AI writes for each section, to help when you use different words from the note.
Private folder	A folder that is findable but locked until you ask to open it.
Agent	The AI app you talk to: Claude, ChatGPT, Codex or another.
MCP	A plug for AI apps. Phygital Engram includes one, so your agent can search your notes directly.

What you get

A ranking tuned for notes. Rare words count more, word roots match ("dashes" finds "dash"), and exact things like versions, IDs and paths match letter for letter.
Folder levels. Rules and context notes count more. Archives and copied code count less.
Age and status. Newer notes count more, halving every 180 days. Done, closed and archived notes sink. Rules never fade.
Folder hints. Say "decisions" or "daily" in your question and that folder counts double. It is a boost, never a filter.
A reason with every result. A short line says why it came back: "exact match", "decision", "3 months old".
Open and look around. Open one section, or the sections before and after it.
A connector for AI apps. Four read-only tools (search_notes, open_result, around_result, check_index) let your agent do all of this itself, from your computer or from your own server. A locked private note can be found but never opened by the agent.
A health check. One command says if the index is fresh, if anything private slipped in, and if searches are slow.
A test you can run on your own notes. Write your own questions and score the search.
Optional note cards. An AI writes a card for each section once, using your own key. About $6 for 4,800 notes, then cents a month. See docs/cards.md.

The search page

Prefer a page to the terminal? Run python3 engram.py page. Your browser opens a small page on your own computer, with the same search your agent uses.

It is dark by default, and light when your computer is. Only this computer can reach it, it loads nothing from the internet, and it cannot change your notes. More in docs/search-page.md.

How fast is it?

On the author's own notes (about 4,800 files, tested 2026-10-25, before tuning):

What	Result
One search	9 to 37 ms on a small server, about 11 ms on a laptop
Build the index from scratch	about 15 seconds
A test copy of 500,000 notes	still answered in 0.23 seconds
104 test questions, without cards	the right note in the top 5 for 90 of 104

These are the author's numbers on one set of private notes, so you cannot rerun them. You can rerun a small public version on made-up notes: see tests/README.md. The method and the limits are in docs/benchmarks.md.

Choose how to run it

Way	Where it runs	Cost	Guide
1. Your computer, from the command line	Mac, Windows or Linux with Python	Free	setup-computer.md
2. Your AI app, through the MCP connector	Your computer, in Claude Code, Claude Desktop, Codex and others	Free	connect-your-ai.md
Claude Desktop extension	Your computer, one click, no config file	Free	claude-desktop-extension.md
3. Your own server	A server you run, for your phone, the Claude website and ChatGPT	A few dollars a month	setup-own-server.md

TIP

Not sure? Start with1. It is free, and nothing leaves your computer. Using an AI coding agent like Claude Code, Codex or Cursor? Ask it to set this up for you: AGENTS.md explains the project to it.

Install in one line

You need a folder of Markdown notes with a file named CLAUDE.md at the top (it can be empty), and Python 3.11 or newer. The full list is in What you need.

Claude Code, from your terminal. Change $HOME/Notes to your notes folder:

claude plugin marketplace add Phygital-Brain/phygital-engram && claude plugin install phygital-engram@phygital-engram --config notes_folder="$HOME/Notes"

Or, inside Claude Code, type this and answer the question about your notes folder:

/plugin install phygital-engram --marketplace Phygital-Brain/phygital-engram

Any AI app, on a Mac or Linux. This downloads the program, builds the index and connects Claude Code if you have it:

curl -fsSL https://raw.githubusercontent.com/Phygital-Brain/phygital-engram/main/install.sh | sh -s -- "$HOME/Notes"

npm. If you have Node.js, install it once:

npm install -g @phygital-brain/engram

Claude Code. Change $HOME/Notes to your notes folder. The index folder must be outside your notes:

claude mcp add phygital-engram --env ENGRAM_VAULT="$HOME/Notes" --env ENGRAM_DATA="$HOME/.phygital-engram/data" -- npx -y @phygital-brain/engram

Any other agent. Add this to your AI app's list of MCP servers (the settings file is usually called mcp.json or claude_desktop_config.json), with your two folders:

{
  "mcpServers": {
    "phygital-engram": {
      "command": "npx",
      "args": ["-y", "@phygital-brain/engram"],
      "env": {
        "ENGRAM_VAULT": "/path/to/your/notes",
        "ENGRAM_DATA": "/path/to/index/folder"
      }
    }
  }
}

Then ask your agent: "Search my notes for the Picture-Book schedule and tell me where you found it." The index builds itself when your agent starts, and it never writes to your notes. For your phone, see setup-own-server.md. More ways: docs/connect-your-ai.md.

What you need

Here is everything Phygital Engram needs, and nothing more.

You need	Why	For
A folder of Markdown notes (`.md` files)	That is what it searches. Obsidian, Baalda and Phygital Brain folders all work	Everything
A file named `CLAUDE.md` at the top of that folder. It can be empty	The search checks it before it indexes, so it never builds an index from a half-copied folder. Phygital Brain makes this file for you. Without it, indexing stops and nothing changes	Everything
A second folder for the index, outside your notes	It keeps its own files there, and refuses to run if that folder is inside your notes	Everything
Python 3.11 or newer	The search uses only what comes with Python, so nothing else to install. Tried on Python 3.11, 3.13 and 3.15	Everything
An AI app that uses MCP (Claude Code, Claude Desktop, Codex and others)	So your agent can search for you. You can also use it from the terminal without one	The AI connector
The MCP SDK (`pip install -r requirements-server.txt`)	Only the server version needs it. The computer version does not	The server version
A server, a domain and your notes on that server	For your phone, the Claude website and ChatGPT. Caddy makes the HTTPS certificate. See setup-own-server.md	The server version
A passphrase of 8 or more characters	You type it once on your own server's login page	The server version
Your own AI key	Only if you turn on note cards. Search works without it	Optional

You don't need an account with us. There is none.

Quick start (about 5 minutes)

NOTE

Version 0.2.1 is an early release. Command and setting names may still change.

Download the latest release and open a terminal in its folder. More in docs/setup-computer.md.
Say where your notes are, and where it may keep its own files. The second folder must be outside your notes:
```
export ENGRAM_VAULT="$HOME/Notes"
```
```
export ENGRAM_DATA="$HOME/phygital-engram-data"
```
Build the index:
```
python3 engram.py ingest
```
You should see a line like indexed 120 ... | 1s, with the number of your notes.
Ask a question:
```
python3 engram.py search "when is the cover due"
```
You should see a short list. Each result shows the note, the heading, a snippet and a line saying why it came back.
Check it is healthy:
```
python3 engram.py health
```
You should see a list of checks with no problems.
Connect your AI app. See docs/connect-your-ai.md.
Ask your agent: "Search my notes for the Picture-Book schedule and tell me where you found it."

Works with Phygital Brain

Phygital Brain builds a folder of notes and keeps it tidy. Phygital Engram searches that folder fast. They are separate on purpose: Phygital Brain stays simple to install, and Phygital Engram works on any Markdown folder, including ones that are not Phygital Brain.

If both are installed, the rules in your brain tell your agent to search first and read files only when the search finds nothing. If Phygital Engram is not installed, nothing breaks: your agent reads files as before.

What it does not do

It does not answer. It finds notes. Your agent reads the result and writes the answer.
It does not search by meaning. It matches words, word roots and exact strings, and uses the folder and age of a note. Optional cards help when you use different words than the note. We tried meaning search: it was about 45 times slower for a small gain. See docs/limits.md.
It does not run in the cloud. It runs on your computer, and there is nothing to sign up for.
It does not sync or back up your notes.
It does not read PDFs, images or Word files. Markdown notes only.

Questions people ask

Yes. It is open source under Apache-2.0. The only cost is the optional note cards, which use your own AI key and cost cents after the first run.

No. It only reads them. Its own files live in a separate folder, and it refuses to run if that folder would be inside your notes.

No, unless you turn on note cards. Cards send section text to the AI service you choose, with secrets blanked first, and never from a private folder.

No. It works on any folder of Markdown notes, including Obsidian vaults.

For a small folder you can. For thousands of notes, reading everything is slow and costs more than it can hold. Search gives your agent the few notes that matter, with their sources.

Yes, through the server version. Phone apps can only reach a connector over HTTPS, so the computer version does not reach your phone. The server version (mcp/serve.py) runs on a server you own, behind a passphrase login. Set it up with setup-own-server.md. It is not tested on a phone with this repository yet. The author uses the working version from a phone through their own server.

All the guides

Guide	Read it when
Getting started	You want the shortest path to your first search
Setup on your computer	You want to install and run it, free
Connect your AI app	You want your agent to search your notes
Setup on your own server	You want your phone, the Claude website or ChatGPT to search your notes
Threat model	You want to know what the server version defends against, and what it does not
Claude Desktop extension	You use Claude Desktop and want one click
The four tools	You want to know what your agent can do with it
The search page	You want to search from a page in your browser
Things to ask	You want ideas for what to ask your agent
The idea behind it	You want to know why plain search works for notes
How it works	You want to know what happens inside
How a search ranks	You want to know why a note came first
Every setting	You want to change how it behaves
Note cards	You want to know about the optional AI summaries
Works with Phygital Brain	You use both
Words you'll see	A term is new to you
Limits	You want to know what it can't do
What we tested	You want the numbers and how they were made
Check the test yourself	You want to run the benchmark on made-up notes
Safety	Before you point it at private folders
Privacy	You want to know what is kept and where
Updates	You want the newest version
Questions people ask	You have a quick question
Troubleshooting	Something doesn't work
Roadmap	You want to know what is planned
SECURITY.md	You found a security problem
CHANGELOG.md	You want to know what changed in each version
CONTRIBUTING.md	You want to report a bug or send a fix
CONTRIBUTORS.md	You want to see who helped, or be added
GOVERNANCE.md	You want to know how decisions are made
SUPPORT.md	You need help and don't know where to ask
AGENTS.md	You (or your AI coding agent) want to change the code or set it up
TRADEMARKS.md	You want to use the name or logo
.env.example	You want every setting in one file

What is next

Phygital Engram is an early release, 0.2.1. Here is where it stands.

What works today. The search runs on the author's own notes. The AI connector works in Claude Code, on your computer and through the server version. The server's login works in a browser, on a desktop and a phone-sized screen. 11 automated tests pass.

What we would like help trying. Tell us how it goes, whether it works or not: open an issue.

The connector in Claude Desktop, Codex, Cursor, VS Code and Gemini CLI.
The server version in Docker, on a real server, and from your phone, the Claude website and ChatGPT. The steps are in setup-own-server.md.
Windows and Linux. So far it has been tried on a Mac.

Not included, on purpose.

Search by meaning. We tried it, and it made searches about 45 times slower for a small gain.
Other languages. Word roots are tuned for English, and other languages match plain words.
PDFs, images and Word files. Only Markdown notes are read.

Security. Phygital Engram has not had an outside security review yet. docs/threat-model.md says how it protects your notes, and SECURITY.md is where to report a problem.

Help and feedback

You want to	Go to
Fix a problem yourself	Troubleshooting
Report a bug	Something doesn't work
Ask a question or share an idea	Question or idea
Report a security problem, privately	Private report (SECURITY.md)

Issues are public, so leave out passwords, keys and private notes.

This repository

Path	What is in it
`app/`	The search page for your own computer, in the Phygital Engram look
`mcp/`	The connectors that let an AI app search your notes. `server.py` runs on your computer. `serve.py` is the server version. Same four read-only tools
`engram.py`, `engram_lib/`, `config.json`	The search itself. It uses only what comes with Python, and `config.json` holds the default settings
`Dockerfile`, `docker-compose.yml`, `Caddyfile`, `requirements-server.txt`	Run the server version on your own server, with HTTPS. The ready-made image is on the Packages page
`.claude-plugin/`, `glama.json`	The Claude Code plugin and the MCP directory listing
`docs/`	Every guide, and the images they use
`tests/`	A made-up sample of 24 notes and 26 questions, so you can run the benchmark yourself
`.github/`	Issue forms, the pull request checklist and the automatic checks
`scripts/`	`check.py`, which checks links, headings and style before every change, and `build_mcpb.py`, which builds the Claude Desktop extension
`AGENTS.md`	A guide for AI coding agents that change this repository
`NOTICE`, `LICENSE`, `TRADEMARKS.md`	The license, the credits and the name and logo rules

Contributors

Thank you to everyone who helped. Code, bug reports, ideas, docs and design all count. See CONTRIBUTORS.md, and add yourself when you send a pull request.

Credits

Phygital Engram was made by Phygital-Brain, next to Phygital Brain. It is not related to other projects that happen to be called Engram.

You are welcome to use, fork, change and build on it under the Apache License 2.0 and the notices in NOTICE. In short:

Keep LICENSE, NOTICE and the copyright lines.
Say where it came from. See TRADEMARKS.md for the words to use.
Mark your version as changed if you changed it.

GitHub's "Cite this repository" button uses CITATION.cff.

No warranty

Phygital Engram is free software you run yourself. It comes as is, with no warranty: you use it at your own risk, and no author is responsible for lost or damaged data (the license says so in full). It never changes your notes, but keep a backup of them anyway.

License

Available Tools

4 tools

around_resultSee what is around a resultA

Read-onlyIdempotent

Show the sections just before and after one result from search_notes, plus other notes written the same day. Read-only. Use it when a result looks right but you need the context around it, such as the step before a decision or the rest of a day. It does not search: it needs a result id.

Name	Required	Description	Default
`id`	Yes	A result id from search_notes

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered and the 'Read-only' sentence partly repeats it. The description earns credit for disclosing the payload shape — adjacent sections plus same-day notes — and the hard prerequisite of a valid result id, which annotations and schema do not convey. It stops short of saying what happens with a stale or invalid id, or how many same-day notes are returned.

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?

Three short sentences, front-loaded with what is returned, then when to use it, then the constraint. Nothing is padded beyond the one-word 'Read-only' line that slightly duplicates the annotations.

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 one-parameter, read-only lookup with no output schema, the description supplies the return content, the usage condition, the non-search exclusion and the required input — everything needed to call it correctly.

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?

Only one parameter, and schema coverage is 100% with the property already documented as 'A result id from search_notes'. The description's 'it needs a result id' restates that provenance rather than adding format or constraint detail, so the baseline of 3 applies.

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?

States a specific verb and resource: shows the sections before and after a given result plus other notes from the same day. It also explicitly contrasts itself with the sibling search_notes by saying it does not search, so an agent can distinguish the two without opening either schema.

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?

Gives a concrete trigger ('when a result looks right but you need the context around it') with examples of what that looks like, and a clear exclusion plus prerequisite ('it does not search: it needs a result id'). It never mentions the sibling open_result, which is the obvious alternative if the agent just wants the full result rather than surrounding context, so routing guidance is clear but not exhaustive.

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

check_indexCheck the indexA

Read-onlyIdempotent

Report whether the search index is fresh, whether anything private slipped in, and whether searches are fast. Read-only: it changes nothing and needs no input. Use it when results look old or missing, or when the person asks if search is healthy.

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so 'Read-only: it changes nothing and needs no input' earns little credit for repeating them. The real added value is disclosing what the check inspects — freshness, possible private-content leakage, and search latency — which the agent could not infer from an empty schema or the annotations, and which matters because there is no output schema.

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?

Two sentences, no waste: the first front-loads what is reported, the second covers safety and invocation timing. Every clause earns its place and nothing is buried.

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 zero-parameter, read-only diagnostic with no output schema, the description covers what is checked, that no input is needed, and when to reach for it. That is everything an agent needs to select and call it correctly.

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?

The tool takes zero parameters, which is the baseline-4 case. The description confirms 'needs no input', consistent with the empty schema, so an agent will not hunt for a required argument.

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 names a specific verb (report) and enumerates the three concrete things it reports: index freshness, private content leakage, and search speed. That is far more specific than the title's 'Check the index' and clearly separates it from the siblings search_notes, open_result and around_result, which retrieve content rather than diagnose the index.

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?

'Use it when results look old or missing, or when the person asks if search is healthy' gives two concrete trigger conditions an agent can match against a conversation. It does not explicitly say when not to use it or name an alternative, but the sibling tools are retrieval tools with no diagnostic overlap, so the boundary is unambiguous.

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

open_resultOpen a resultA

Read-onlyIdempotent

Open one result from search_notes by its id and return the full section of the note, or the whole note if it is short. Read-only. Use it after search_notes, when a snippet is not enough to answer. An id that no longer exists returns a not-found message: search again. A LOCKED private note is refused, and the person must open it themselves.

Name	Required	Description	Default
`id`	Yes	A result id from search_notes

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already cover read-only/idempotent/non-destructive, yet the description adds genuinely new behavior: a missing id yields a not-found message rather than an error, and a LOCKED private note is refused so the person must open it themselves. Those refusal and failure modes are exactly the context annotations cannot express.

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?

Four short sentences, front-loaded with the action and return shape, then usage, then edge cases. Every sentence carries distinct information; nothing is repeated.

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?

With no output schema, the description still specifies the return granularity (section vs. whole note), the not-found path, and the locked-note refusal. An agent has everything needed to call it and interpret the outcome.

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?

Schema coverage is 100% and the single 'id' param is already documented as 'A result id from search_notes', so the description only restates that provenance. Baseline 3 is right for one fully documented parameter with no added syntax or format detail.

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?

Names a specific verb (open) and resource (one result from search_notes) and states what comes back: the full section, or the whole note if short. That return-behavior contrast with search_notes' snippets makes it instantly distinguishable from the sibling.

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

Usage Guidelines5/5

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

Explicit sequencing ('Use it after search_notes, when a snippet is not enough to answer') gives both the prerequisite and the trigger condition, and it names the alternative (search_notes) by implication. It also tells the agent what to do on a stale id: search again.

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

search_notesSearch notesA

Read-onlyIdempotent

Search the person's Markdown notes with plain words and get a short ranked list. Use it first, before you answer about their past work, projects, decisions, people or notes. Read-only. Each result has an id, the note path, the heading, the date, a snippet and a line saying why it came back (for example an exact match or a decision note). Results can include a private note marked LOCKED: tell the person it exists and let them open it. Pass an id to open_result for the full text. If nothing matches, the list is empty.

Name	Required	Description	Default
`limit`	No	How many results (default 8)
`query`	Yes	The question, in plain words (up to 500 characters)

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the annotations: it enumerates the result fields, explains the 'why it came back' reason, documents the LOCKED private-note case with an explicit instruction to tell the person rather than silently surfacing it, and states that a miss returns an empty list. Read-only/idempotent are already in annotations, and the description adds real operating context on top.

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

Conciseness4/5

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

Purpose is front-loaded in the first sentence, and each subsequent sentence carries distinct information (read-only, result shape, LOCKED handling, follow-up via open_result, empty result). The domain enumeration in sentence two is slightly long but still purposeful.

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?

There is no output schema, so the description carries the return-value burden and does so fully: field list, match-reason string, locked-note handling, and the empty-result case. Combined with annotation coverage of the safety profile, an agent has everything needed to call and interpret it.

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?

Schema coverage is 100%, so both parameters are already documented in the schema. The description adds only the loose notion of 'plain words' and 'short ranked list', which hints at the query style and default limit but adds no syntax or format 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?

Names a specific verb (search) and resource (the person's Markdown notes), states the input style (plain words) and the output shape (short ranked list). It also signals the relationship to open_result, so an agent can place it among siblings without opening a schema.

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?

"Use it first, before you answer about their past work, projects, decisions, people or notes" gives a clear priority rule and names the domains it covers. It also points to open_result for full text, though the other siblings (check_index, around_result) are never mentioned, so there is no explicit exclusion or fallback path.

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.

4 tool updatesOct 25, 2026
- First observedaround_result
- First observedcheck_index
- First observedopen_result
- 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

A4.4/5.0

Scored 2026-10-25 23:05 across 4 tools

Disambiguation5/5

Each tool has a clearly distinct role: search_notes finds results, open_result expands one result, around_result provides surrounding context, and check_index reports index health. The descriptions explicitly state when to use each and how they chain, leaving little room for misselection.

Naming Consistency4/5

All names use consistent snake_case and a short two-word form, mostly following an action_noun pattern (search_notes, open_result, check_index). The exception is around_result, where 'around' is positional rather than a verb, but it remains readable and predictable.

Tool Count5/5

Four tools is a well-scoped set for a read-only note-search server, with each tool covering a distinct step in the retrieval workflow. There is no redundant or obviously missing tool for the core purpose.

Completeness4/5

The surface covers the key lifecycle of searching, opening, inspecting context around, and checking search health. Minor gaps exist, such as no explicit way to list recent notes or filter searches by date, but agents can largely work around these through search and around_result.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

sensefold AOAuth
app.sensefold
Personal context for every AI: search, read, and write back to your private Markdown library.
Knowledge & Memory Note Taking Search
1
https://api.sensefold.app/mcp
sunub-obsidian-mcp-server
ai.smithery
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Note Taking Search Text Summarization
22
https://server.smithery.ai/@sunub/obsidian-mcp-server/mcp
PhasoricOAuth
io.github.aketchel
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Note Taking Knowledge & Memory
1
https://phasoric.com/api/mcp
ThinkerNotesOAuth
com.thinkernotes
Search and read your own notes: insights, drafts, book and podcast notes. Read-only, OAuth.
Note Taking Search
1
https://thinkernotes.com/mcp

Related MCP Servers

Keepygaga RAG
RAG Systems Search
TimWongUp
A
license
A
quality
C
maintenance
Enables local-first hybrid knowledge retrieval from authorized Markdown and plain-text files, combining full-text and vector search with reranking and traceable source references via a single search tool.
Updated 8 days ago (2026-10-19 22:12 UTC)
1
MIT
second-brain-mcp
Note Taking Knowledge & Memory RAG Systems
gmoorevt
A
license
Not graded
quality
C
maintenance
Enables AI assistants to file notes into a self-hosted Obsidian vault and retrieve them later through structured and semantic search over plain Markdown.
Updated 2 months ago (2026-09-07 10:51 UTC)
MIT
plainmem-mcp
Knowledge & Memory Note Taking RAG Systems
HarshShroff
A
license
Not graded
quality
B
maintenance
Gives AI agents a long-term memory layer over plain Markdown notes, letting them run ranked, citable searches, record new facts, and inspect conflicts and stale entries. Results carry freshness labels, supersession history, and audit fields like search timestamp and no-match status so agents can prove a search actually ran.
Updated 14 days ago (2026-10-14 02:02 UTC)
MIT
Selfhost-Remote-Mail-MCP
Communication Email Workplace & Productivity
Self-hosted-MCP
A
license
A
quality
A
maintenance
Enables AI apps to securely read, search, organize, draft, attach files to, and send email across up to five self-hosted IMAP/SMTP mailboxes, with sending only after explicit user approval.
Updated 4 days ago (2026-10-23 22:43 UTC)
18
AGPL 3.0