Skip to main content
Glama
Phygital Engram

Phygital Engram

Official
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: 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

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, Phygital Memory 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.3.0 is an early release. Command and setting names may still change.

  1. Download the latest release and open a terminal in its folder. More in docs/setup-computer.md.

  2. 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"
  3. Build the index:

    python3 engram.py ingest

    You should see a line like indexed 120 ... | 1s, with the number of your notes.

  4. 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.

  5. Check it is healthy:

    python3 engram.py health

    You should see a list of checks with no problems.

  6. Connect your AI app. See docs/connect-your-ai.md.

  7. 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

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.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

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

Apache License 2.0, with the notices in NOTICE. Copyright (C) 2026 Phygital-Brain and Phygital Engram contributors.

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.

Inputs: id (required).

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.

Inputs: no named parameters.

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.

Inputs: id (required).

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.

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

    A4.4/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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'.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives 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