<p align="center"><img src="docs/images/icon.png" alt="" width="88"></p>

<h1 align="center">Phygital Engram</h1>

<p align="center"><b>Your notes, found in milliseconds.</b><br>Phygital Engram is a fast, private search for your second brain, or any folder of Markdown notes. Your agent finds the right note and the exact line, with where it came from. Nothing leaves your computer.</p>

<p align="center">
<a href="#credits"><img src="https://img.shields.io/badge/-open%20source-FFD60A" alt="Open source"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
<a href="https://github.com/Phygital-Brain/phygital-engram/stargazers"><img src="https://img.shields.io/github/stars/Phygital-Brain/phygital-engram?style=flat" alt="GitHub stars"></a>
<a href="docs/how-it-works.md"><img src="https://img.shields.io/badge/notes-Markdown-0B0D12?logo=markdown&labelColor=FFD60A" alt="Notes: plain Markdown"></a>
<a href="docs/safety.md"><img src="https://img.shields.io/badge/notes-read--only-0B0D12?labelColor=9B8CFF" alt="Your notes are read-only"></a>
<a href="docs/privacy.md"><img src="https://img.shields.io/badge/telemetry-none-0B0D12?labelColor=FFD60A" alt="No telemetry"></a>
<a href="docs/tools.md"><img src="https://img.shields.io/badge/MCP-connector-black" alt="Includes an MCP connector for AI apps"></a>
<a href="docs/benchmarks.md"><img src="https://img.shields.io/badge/search-about%2011%20ms-0B0D12?labelColor=9B8CFF" alt="About 11 ms per search on the author's notes"></a>
</p>
<p align="center">
<a href="https://github.com/Phygital-Brain/phygital-engram/actions/workflows/tests.yml"><img src="https://github.com/Phygital-Brain/phygital-engram/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
<a href="https://github.com/Phygital-Brain/phygital-engram/releases/latest"><img src="https://img.shields.io/github/v/release/Phygital-Brain/phygital-engram?include_prereleases" alt="Latest release"></a>
<a href="https://github.com/Phygital-Brain/phygital-engram/commits/main"><img src="https://img.shields.io/github/last-commit/Phygital-Brain/phygital-engram" alt="Last commit"></a>
<a href="docs/roadmap.md"><img src="https://img.shields.io/badge/status-early%20release-0B0D12?labelColor=FFD60A" alt="Status: early release, version 0.2.1"></a>
<a href="https://github.com/Phygital-Brain/phygital-brain"><img src="https://img.shields.io/badge/made%20for-Phygital%20Brain-F05AB8" alt="Made to work with Phygital Brain"></a>
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-5AC8FA" alt="Pull requests welcome"></a>
</p>

<p align="center"><b>Free and open source under the Apache-2.0 license.</b> Use it, fork it and change it, share your changes, and keep the credit. See <a href="#credits">Credits</a>.</p>

<p align="center">
<a href="#what-it-is">What it is</a> ·
<a href="#how-fast-is-it">How fast</a> ·
<a href="#install-in-one-line">Install in one line</a> ·
<a href="#quick-start-about-5-minutes">Quick start</a> ·
<a href="docs/connect-your-ai.md">Connect your AI app</a> ·
<a href="#safety-and-privacy">Safety and privacy</a> ·
<a href="docs/examples.md">Things to ask</a> ·
<a href="#works-with-phygital-brain">Phygital Brain</a> ·
<a href="#all-the-guides">All guides</a>
</p>

<details>
<summary><b>Table of contents</b></summary>

- [What it is](#what-it-is)
- [Why it exists](#why-it-exists)
- [Safety and privacy](#safety-and-privacy)
- [How it works, in one picture](#how-it-works-in-one-picture)
- [Words you'll see](#words-youll-see)
- [What you get](#what-you-get)
- [The search page](#the-search-page)
- [How fast is it?](#how-fast-is-it)
- [Choose how to run it](#choose-how-to-run-it)
- [Install in one line](#install-in-one-line)
- [What you need](#what-you-need)
- [Quick start (about 5 minutes)](#quick-start-about-5-minutes)
- [Works with Phygital Brain](#works-with-phygital-brain)
- [What it does not do](#what-it-does-not-do)
- [Questions people ask](#questions-people-ask)
- [All the guides](#all-the-guides)
- [What is next](#what-is-next)
- [Help and feedback](#help-and-feedback)
- [This repository](#this-repository)
- [Contributors](#contributors)
- [Credits](#credits)
- [No warranty](#no-warranty)
- [License](#license)

</details>

> [!NOTE]
> Works with any folder of Markdown notes, and is made to sit beside [Phygital Brain](https://github.com/Phygital-Brain/phygital-brain). It is not related to other projects that happen to be called Engram.

<p align="center"><img src="docs/images/hero.png" alt="You ask when the cover is due. Phygital Engram returns three results in about 11 milliseconds. The first is the Picture-Book schedule, with its note, heading and date as the source. Your agent answers that the cover is due on the 15th." width="100%"></p>

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

## 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. Read [docs/safety.md](docs/safety.md) before you point it at private folders.

<p align="center"><img src="docs/images/ownership.png" alt="Two separate places. Your notes folder is read-only and is never changed, moved or deleted. Phygital Engram keeps its own index in its own folder, and you can delete it at any time because it rebuilds." width="640"></p>

- 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](docs/safety.md) and [docs/privacy.md](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.

<p align="center"><img src="docs/images/how-it-works.png" alt="Five steps from your notes to your agent: your notes, a list of them kept outside your folder, the ranking, a short list of results with note, heading and date, and your agent opening the best one and answering." width="640"></p>

More in [docs/how-it-works.md](docs/how-it-works.md) and [docs/search-ranking.md](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

<p align="center"><img src="docs/images/ranking.png" alt="Six steps that decide the order of results: your words, exact things like versions and file paths, where the note lives, whether it is done or old, how new it is, and a tidy list with at most 2 sections per note." width="640"></p>

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

<p align="center"><img src="docs/images/page.png" alt="The Phygital Engram search page. The question when is the cover due returns the Schedule note first, with its path in violet, the matched words highlighted, and links to open the note, show the full section, see what is around it and copy the path." width="760"></p>

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](docs/search-page.md).

## How fast is it?

<p align="center"><img src="docs/images/benchmark.png" alt="Benchmark. The right note is in the top 5 for 48 of 56 tuning questions and 42 of 48 hidden questions, against 40 of 56 for word match only. A search takes about 11 milliseconds, against about 495 for a search by meaning that we tried. 104 questions on one person's notes, measured 2026-10-25 before tuning." width="100%"></p>

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](tests/README.md). The method and the limits are in [docs/benchmarks.md](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](docs/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](docs/connect-your-ai.md) |
| Claude Desktop extension | Your computer, one click, no config file | Free | [claude-desktop-extension.md](docs/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](docs/setup-own-server.md) |

> [!TIP]
> Not sure? Start with **1**. 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](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](#what-you-need).

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

```bash
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:

```bash
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:

```bash
npm install -g @phygital-brain/engram
```

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

```bash
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:

```json
{
  "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](docs/setup-own-server.md). More ways: [docs/connect-your-ai.md](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](docs/with-phygital-brain.md) 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](docs/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](docs/cards.md). 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.

1. Download the [latest release](https://github.com/Phygital-Brain/phygital-engram/releases/latest) and open a terminal in its folder. More in [docs/setup-computer.md](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:

   ```bash
   export ENGRAM_VAULT="$HOME/Notes"
   ```

   ```bash
   export ENGRAM_DATA="$HOME/phygital-engram-data"
   ```

3. Build the index:

   ```bash
   python3 engram.py ingest
   ```

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

4. Ask a question:

   ```bash
   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:

   ```bash
   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](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](docs/getting-started.md).

## Works with Phygital Brain

[Phygital Brain](https://github.com/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](docs/with-phygital-brain.md).

## 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](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

<details>
<summary><b>Is it free?</b></summary>

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

<details>
<summary><b>Does it change my notes?</b></summary>

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

<details>
<summary><b>Does it send my notes anywhere?</b></summary>

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

<details>
<summary><b>Do I need Phygital Brain?</b></summary>

No. It works on any folder of Markdown notes, including Obsidian vaults.
</details>

<details>
<summary><b>Why not let my agent read the folder itself?</b></summary>

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

<details>
<summary><b>Can I use it from my phone?</b></summary>

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](docs/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.
</details>

More in [docs/faq.md](docs/faq.md).

## All the guides

| Guide | Read it when |
|---|---|
| [Getting started](docs/getting-started.md) | You want the shortest path to your first search |
| [Setup on your computer](docs/setup-computer.md) | You want to install and run it, free |
| [Connect your AI app](docs/connect-your-ai.md) | You want your agent to search your notes |
| [Setup on your own server](docs/setup-own-server.md) | You want your phone, the Claude website or ChatGPT to search your notes |
| [Threat model](docs/threat-model.md) | You want to know what the server version defends against, and what it does not |
| [Claude Desktop extension](docs/claude-desktop-extension.md) | You use Claude Desktop and want one click |
| [The four tools](docs/tools.md) | You want to know what your agent can do with it |
| [The search page](docs/search-page.md) | You want to search from a page in your browser |
| [Things to ask](docs/examples.md) | You want ideas for what to ask your agent |
| [The idea behind it](docs/the-idea.md) | You want to know why plain search works for notes |
| [How it works](docs/how-it-works.md) | You want to know what happens inside |
| [How a search ranks](docs/search-ranking.md) | You want to know why a note came first |
| [Every setting](docs/settings.md) | You want to change how it behaves |
| [Note cards](docs/cards.md) | You want to know about the optional AI summaries |
| [Works with Phygital Brain](docs/with-phygital-brain.md) | You use both |
| [Words you'll see](docs/glossary.md) | A term is new to you |
| [Limits](docs/limits.md) | You want to know what it can't do |
| [What we tested](docs/benchmarks.md) | You want the numbers and how they were made |
| [Check the test yourself](tests/README.md) | You want to run the benchmark on made-up notes |
| [Safety](docs/safety.md) | Before you point it at private folders |
| [Privacy](docs/privacy.md) | You want to know what is kept and where |
| [Updates](docs/updates.md) | You want the newest version |
| [Questions people ask](docs/faq.md) | You have a quick question |
| [Troubleshooting](docs/troubleshooting.md) | Something doesn't work |
| [Roadmap](docs/roadmap.md) | You want to know what is planned |
| [SECURITY.md](SECURITY.md) | You found a security problem |
| [CHANGELOG.md](CHANGELOG.md) | You want to know what changed in each version |
| [CONTRIBUTING.md](CONTRIBUTING.md) | You want to report a bug or send a fix |
| [CONTRIBUTORS.md](CONTRIBUTORS.md) | You want to see who helped, or be added |
| [GOVERNANCE.md](GOVERNANCE.md) | You want to know how decisions are made |
| [SUPPORT.md](SUPPORT.md) | You need help and don't know where to ask |
| [AGENTS.md](AGENTS.md) | You (or your AI coding agent) want to change the code or set it up |
| [TRADEMARKS.md](TRADEMARKS.md) | You want to use the name or logo |
| [.env.example](.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](https://github.com/Phygital-Brain/phygital-engram/issues/new?template=question.yml).

- 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](docs/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](docs/threat-model.md) says how it protects your notes, and [SECURITY.md](SECURITY.md) is where to report a problem.

## Help and feedback

| You want to | Go to |
|---|---|
| Fix a problem yourself | [Troubleshooting](docs/troubleshooting.md) |
| Report a bug | [Something doesn't work](https://github.com/Phygital-Brain/phygital-engram/issues/new?template=bug_report.yml) |
| Ask a question or share an idea | [Question or idea](https://github.com/Phygital-Brain/phygital-engram/issues/new?template=question.yml) |
| Report a security problem, privately | [Private report](https://github.com/Phygital-Brain/phygital-engram/security/advisories/new) ([SECURITY.md](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](https://github.com/Phygital-Brain/phygital-engram/pkgs/container/phygital-engram) |
| `.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](CONTRIBUTORS.md), and add yourself when you send a pull request.

## Credits

Phygital Engram was made by [Phygital-Brain](https://github.com/Phygital-Brain), next to [Phygital Brain](https://github.com/Phygital-Brain/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](NOTICE). In short:

- Keep [LICENSE](LICENSE), [NOTICE](NOTICE) and the copyright lines.
- Say where it came from. See [TRADEMARKS.md](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](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](LICENSE) says so in full). It never changes your notes, but keep a backup of them anyway.

## License

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