Phygital Engram
OfficialThis MCP server provides read-only search and context access to a person's Markdown notes.
Search notes (
search_notes): search with plain words, returning a short ranked list with ids, note paths, headings, dates, snippets, and match reasons; supports optional folder filtering,limitup to 20 (default 8), and queries up to 500 characters.Open a result (
open_result): retrieve the full note section or whole short note by result id; locked private notes are refused.See surrounding context (
around_result): show sections before and after a result plus other notes from the same day.Check index health (
check_index): report whether the index is fresh, whether private content slipped in, and whether searches are fast.All tools are read-only, idempotent, non-destructive, and do not access external services.
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.
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: plainmem-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
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.
.envfiles, key files andcredentials.jsonare 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.claudeignoreand hidden folders like.obsidianand.gitare 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 | |
2. Your AI app, through the MCP connector | Your computer, in Claude Code, Claude Desktop, Codex and others | Free | |
Claude Desktop extension | Your computer, one click, no config file | Free | |
3. Your own server | A server you run, for your phone, the Claude website and ChatGPT | A few dollars a month |
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-engramAny 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/engramClaude 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/engramAny 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 ( | That is what it searches. Obsidian, Phygital Memory and Phygital Brain folders all work | Everything |
A file named | 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 ( | 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)
Version 0.3.0 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 ingestYou 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 healthYou 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."
More in docs/getting-started.md.
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.
More in docs/with-phygital-brain.md.
Built into Phygital Memory
Phygital Memory is a free, open source notes app for Mac, Windows and Linux, with Phygital Engram built in. Its search, and the search your AI apps use through it, run on Phygital Engram, with nothing extra to install. If you use Phygital Memory, you already have it.
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.
More in docs/faq.md.
All the guides
Guide | Read it when |
You want the shortest path to your first search | |
You want to install and run it, free | |
You want your agent to search your notes | |
You want your phone, the Claude website or ChatGPT to search your notes | |
You want to know what the server version defends against, and what it does not | |
You use Claude Desktop and want one click | |
You want to know what your agent can do with it | |
You want to search from a page in your browser | |
You want ideas for what to ask your agent | |
You want to know why plain search works for notes | |
You want to know what happens inside | |
You want to know why a note came first | |
You want to change how it behaves | |
You want to know about the optional AI summaries | |
You use both | |
A term is new to you | |
You want to know what it can't do | |
You want the numbers and how they were made | |
You want to run the benchmark on made-up notes | |
Before you point it at private folders | |
You want to know what is kept and where | |
You want the newest version | |
You have a quick question | |
Something doesn't work | |
You want to know what is planned | |
You found a security problem | |
You want to know what changed in each version | |
You want to report a bug or send a fix | |
You want to see who helped, or be added | |
You want to know how decisions are made | |
You need help and don't know where to ask | |
You (or your AI coding agent) want to change the code or set it up | |
You want to use the name or logo | |
You want every setting in one file |
What is next
Phygital Engram is an early release, 0.3.0. 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 | |
Report a bug | |
Ask a question or share an idea | |
Report a security problem, privately |
Issues are public, so leave out passwords, keys and private notes.
This repository
Path | What is in it |
| The search page for your own computer, in the Phygital Engram look |
| The connectors that let an AI app search your notes. |
| The search itself. It uses only what comes with Python, and |
| Run the server version on your own server, with HTTPS. The ready-made image is on the Packages page |
| The Claude Code plugin and the MCP directory listing |
| Every guide, and the images they use |
| A made-up sample of 24 notes and 26 questions, so you can run the benchmark yourself |
| Issue forms, the pull request checklist and the automatic checks |
|
|
| A guide for AI coding agents that change this repository |
| 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:
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
Apache License 2.0, with the notices in NOTICE. Copyright (C) 2026 Phygital-Brain and Phygital Engram contributors.
Available Tools
4 toolsaround_resultSee what is around a resultARead-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.
Inputs: id (required).
check_indexCheck the indexARead-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.
Inputs: no named parameters.
open_resultOpen a resultARead-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.
Inputs: id (required).
search_notesSearch notesARead-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.
Inputs: query (required), limit, folder.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The four tools split cleanly by input contract: search_notes takes a query, open_result and around_result take a result id, and check_index takes nothing. The only soft overlap is between open_result and around_result, since both return note text for an id, but the descriptions explicitly separate 'full section' from 'surrounding context' and even state that around_result does not search.
All four names are snake_case verb_noun pairs (search_notes, open_result, around_result, check_index), matching the expected pattern. The minor deviation is 'around_result', which uses a preposition rather than an action verb and shifts the object noun from 'notes' to 'result'.
Four tools cover a tight read-only retrieval loop — discover, open, expand context, verify health — and each earns its place with no redundant surface. It sits at the low end, but nothing feels gratuitous; the only pressure toward a fifth tool is a browse/list path that doesn't exist.
The stated purpose (search a person's notes and open what you find) is fully covered, including context expansion and a self-diagnostic for stale or private content. The gap is enumeration: there is no way to list recent notes, browse by date, or enumerate people/tags, so questions like 'what did I work on last week' depend entirely on guessing search terms, only partly mitigated by around_result returning same-day notes.
Maintenance
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Search and read your own notes: insights, drafts, book and podcast notes. Read-only, OAuth.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to file notes into a self-hosted Obsidian vault and retrieve them later through structured and semantic search over plain Markdown.MIT
- AlicenseNot gradedqualityBmaintenanceGives 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.MIT
- AlicenseAqualityBmaintenanceEnables 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.18AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceGives AI agents fast, read-only access to a local knowledge base of Markdown notes and other text documents via a SQLite full-text index. Enables ranked section-level search, reading whole notes or single sections, heading outlines, note listing, and link/backlink navigation without slow disk walks.Apache 2.0