markdown-memory MCP server
Commit Nov 1, 2026Provides coding agents with precise Markdown sections using local hybrid search with BM25 and ONNX embeddings in SQLite.
Also known as hishamkaram/markdown-memory
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 1, 2026
- License
- MIT
What is markdown-memory MCP?
markdown-memory provides coding agents with precise Markdown sections using local hybrid search with BM25 and ONNX embeddings in SQLite.
Summary generated from the project's README
About markdown-memory MCP server
Helping coding agents find specific answers within large documentation sets is what markdown-memory achieves by replacing full file reads with precise section retrieval. Instead of forcing an AI to process thousands of tokens from an entire file, this local MCP server indexes Markdown files by heading and returns only the relevant passage and its immediate neighbors. This significantly reduces token usage and context noise for agents using tools like Claude Code or Codex.
The server runs entirely on your machine using Python, SQLite, and ONNX embeddings, ensuring no data leaves your local environment. It utilizes a hybrid search approach combining BM25 keyword matching with vector search via the EmbeddingGemma-300m model. Users can interact with the server through tools such as search_docs, read_section, get_document_outline, and list_documents. Setup requires Python 3.11 or newer and the uv package manager, with a one-time download of approximately 218 MB for the embedding model.
What you can do with it
- 1Reduce documentation token costsAn agent can retrieve a 275-token excerpt instead of reading a 21,511-token documentation set.
- 2Perform private local searchesUsers can search their proprietary documentation without sending data to an external API.
- 3Deep dive into specific sectionsIf a brief excerpt is insufficient, an agent can request the full content of a specific heading.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
MARKDOWN_MEMORY_DOCS_DIRMARKDOWN_MEMORY_EXCLUDE
| Name | Description | |
|---|---|---|
| MARKDOWN_MEMORY_DOCS_DIR | — | |
| MARKDOWN_MEMORY_EXCLUDE | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehishamkaram/markdown-memory is public and reachablegithub.com/hishamkaram/markdown-memory ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-01github.com/hishamkaram/markdown-memory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmarkdown-memory
Your coding agent reads whole Markdown files to answer one question. This returns the section that answers it.
Ask an agent a question about your docs and it opens the files that might answer it, whole. Most of what lands in its context is about something else, and the part you wanted competes with it. markdown-memory indexes your documentation by heading, so the same question comes back as the section that answers it - or, when that section is long, the passage that matched and its neighbours - quoted verbatim, with pointers to the next few.
Measured on this repository's own documentation - README.md, CLAUDE.md, AGENTS.md and
docs/evaluation-protocol.md, 21,511 tokens in all:
search_docs("where does the embedding model get downloaded")
407 tok README.md markdown-memory > The embedding model > What downloads, when, and where
excerpt: the passage that matched and the three after it come back (275 tok)
764 tok README.md markdown-memory > The embedding model > Pre-download it, or install offline
787 tok README.md markdown-memory
303 tok README.md markdown-memory > The embedding model > When it goes wrong
119 tok README.md markdown-memory > Install > Get it
A 275-token excerpt in a ~608-token call, instead of 21,511: the passage that answers and
the three after it, verbatim, marked excerpt: true - one read_section returns
the whole 407-token section when that is not enough. The other four come back as pointers -
where each section is, what reading it costs, and the passage that matched - so when the first
is not the answer, one read_section fetches the one that is. The call is everything
search_docs sends: the excerpt, the pointers and index_status, plus the path of your
checkout, which it names in full.
It is a local Model Context Protocol server - MCP is the
protocol agents use to call tools - and it runs entirely on your machine: parsing with
markdown-it-py, embeddings with
EmbeddingGemma-300m
(4-bit ONNX on CPU, 768 dimensions), storage in SQLite - one database per documentation
root and preset, with a keyword index and two vector indexes over it. No API key, no network after the
first model download, nothing leaves the machine.
Install
Prerequisites
- Python 3.11 or newer. The project develops on 3.12 and CI runs 3.11 through 3.14 on x86-64 Linux.
- uv, which manages the interpreter and the dependencies:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux - Roughly 1 GB of disk: ~218 MB for the embedding model, the rest for the index.
- Linux or macOS, x86-64 or arm64. Everything runs on CPU; there is no GPU path and no API
key. CI covers arm64 Linux on every change and Apple Silicon on
main, because the 4-bit graph picks itsMatMulNBitskernel from what the CPU offers rather than from the file - see What downloads, when, and where. Those kernels do not all return the same numbers: the gate measures four CPU families and the same text embeds up to 1.6e-3 cosine apart between x86-64 and arm64. Copying an index between two machines therefore searches vectors from one kernel with queries from another, which nothing detects - and which was measured, on the labelled set and through the real ranking, to move no top result and lose no answer. It reshuffles positions two to five.
Get it
uv tool install markdown-memory # or: pipx install markdown-memory
markdown-memory --download-model # optional: fetch the ~218 MB model now
uv tool install puts the markdown-memory command in ~/.local/bin; if your shell cannot
find it, uv tool update-shell adds that directory to your PATH. Fetching the model up
front is optional - the first search does it otherwise - but it keeps a 218 MB download
out of your first question.
Register it with your client
One registration serves every project. The server indexes the project the client was
started in - Claude Code tells it (CLAUDE_PROJECT_DIR), Codex starts it there - and each
project gets its own index.
claude mcp add --scope user markdown-memory -- markdown-memory # Claude Code
codex mcp add markdown-memory -- markdown-memory # Codex
claude mcp list and codex mcp list should show it. Upgrade with
uv tool upgrade markdown-memory (or pipx upgrade markdown-memory); remove it with
claude mcp remove --scope user markdown-memory, codex mcp remove markdown-memory and
uv tool uninstall markdown-memory (or pipx uninstall markdown-memory).
Desktop apps (Claude Desktop, Cursor) usually do not see ~/.local/bin, so give them the
absolute path that command -v markdown-memory prints. Claude Desktop has no project
either, so name the documentation root:
{
"mcpServers": {
"markdown-memory": {
"command": "/home/you/.local/bin/markdown-memory",
"env": { "MARKDOWN_MEMORY_DOCS_DIR": "/absolute/path/to/your/docs" }
}
}
}
uvx markdown-memory works in place of the installed command too, with one catch: its
first launch downloads about 250 MB of dependencies before the server can answer, longer
than Codex waits by default - set startup_timeout_sec = 60 under
[mcp_servers.markdown-memory] in ~/.codex/config.toml if you go that way.
Tell Codex to use it
Registered, the server is one of Codex's tools, but a default Codex may never look for it. In code
mode the model finds MCP tools by searching its tool list, and it searches for what its
instructions name. Add this line to the repository's AGENTS.md (create the file if there is
none):
- For questions about this repository's documentation, call the `search_docs` tool (markdown-memory MCP server) before grepping or reading Markdown files; use `read_section` only when the text it returns is not enough.
Measured in a paired A/B trial on 40 documentation questions over uv and vite
(#134, protocol in
docs/adoption-trial/step-d.md). A default Codex (CLI 0.164.0,
gpt-6.1-sol) called the server in 0/40 sessions without the line and in 40/40 with it (95%
interval 91-100%). Answer accuracy did not drop by the trial's harm guard. Those were authored
tasks, not real use. Claude Code already called it in every session either way.
Headless and sandboxed agents
Registering the server gives an agent no permission to call it. An interactive session can ask
you; a headless one - claude -p, codex exec, a CI job - has nobody to ask, so the client
refuses the call and the server never sees it:
Claude requested permissions to use mcp__markdown-memory__search_docs, but you haven't granted it yet.
Cannot call mcp__markdown-memory__search_docs while in plan mode.
MCP tool call requires approval, but approval policy is never
Allow the four retrieval tools - search_docs, read_section, get_document_outline and
list_documents - and leave index_directory out: by default the server keeps its own root
indexed. The four do not edit your Markdown or source files, but they do write markdown-memory's
own state: search_docs, and list_documents called without a directory, can start the
background catch-up index, and on a cold cache search_docs downloads the model (~218 MB with the
default preset). By default the index lives outside the repository; a MARKDOWN_MEMORY_DB you set
puts it wherever that path points, and a relative one is resolved against the project root.
Claude Code takes them on the command line:
claude -p --allowedTools "mcp__markdown-memory__search_docs,mcp__markdown-memory__read_section,mcp__markdown-memory__get_document_outline,mcp__markdown-memory__list_documents" "your prompt"
or, for every session, in ~/.claude/settings.json:
{
"permissions": {
"allow": [
"mcp__markdown-memory__search_docs",
"mcp__markdown-memory__read_section",
"mcp__markdown-memory__get_document_outline",
"mcp__markdown-memory__list_documents"
]
}
}
A repository's own .claude/settings.json does not work for this: claude -p ignores its allow
rules in a folder that was never trusted
(Claude Code docs).
Plan mode (--permission-mode plan) refuses these tools even when they are allowed; use the
default mode, or --permission-mode dontAsk, which runs the allowed tools and refuses the rest.
Codex takes them in ~/.codex/config.toml:
[mcp_servers.markdown-memory.tools.search_docs]
approval_mode = "approve"
[mcp_servers.markdown-memory.tools.read_section]
approval_mode = "approve"
[mcp_servers.markdown-memory.tools.get_document_outline]
approval_mode = "approve"
[mcp_servers.markdown-memory.tools.list_documents]
approval_mode = "approve"
or for one run:
codex exec \
-c 'mcp_servers.markdown-memory.tools.search_docs.approval_mode="approve"' \
-c 'mcp_servers.markdown-memory.tools.read_section.approval_mode="approve"' \
-c 'mcp_servers.markdown-memory.tools.get_document_outline.approval_mode="approve"' \
-c 'mcp_servers.markdown-memory.tools.list_documents.approval_mode="approve"' \
"your prompt"
That skips Codex's approval check for those tools, unless strict auto-review is on. Verified with Claude Code 2.1.294 and Codex CLI 0.161.0; how clients ask for approval changes between versions.
From source
For working on markdown-memory itself:
git clone https://github.com/hishamkaram/markdown-memory
cd markdown-memory
uv sync
uv run markdown-memory --version
The .mcp.json in the clone runs that checkout (uv run markdown-memory) whenever Claude
Code is opened in it, with no edit.
Index once, then search
The server keeps its documentation root indexed by itself. The first search_docs (or
list_documents without a directory) after it starts begins a catch-up run in the
background - whatever changed while no server ran, new files included - and answers from
the index as it stood, with index_status.indexing set. Nothing runs before that first
call: loading the model holds the interpreter for seconds, and a client waiting on the
handshake gives up quickly. After that, each of those calls decides whether another run is
due:
- a file it sees edited, deleted or unreadable starts one, at most every 10 seconds;
- a weights mismatch a search has just recorded starts one at once;
- otherwise one walks the tree every 5 minutes while the server is in use, which is what finds a file nobody indexed yet.
One run at a time, in one thread, stopped between two documents when the server shuts down;
a stopped run leaves what a killed run leaves, and the next one resumes. While it runs,
index_status.indexing is true and the message says so instead of asking for
index_directory. Nothing watches the filesystem, so a server nobody is using does not
spend anything; read_section and get_document_outline do not start a run. The first
run of a large tree embeds everything and competes with queries for CPU until it is done;
--no-auto-index (or MARKDOWN_MEMORY_AUTO_INDEX=0) turns all of this off, and then:
index_directory() # scans the docs root, embeds what it finds
list_documents() # index_status.coverage should read "verified"
The first run downloads the embedding model and then indexes, so it is the slow one - see
The embedding model. After that, indexing is incremental: re-running
it costs milliseconds when nothing changed. If coverage reads "unknown", something was
missed and index_status.message says what to run.
index_status also carries changed_files: indexed documents a cheap probe could not
confirm are still what was indexed - their bytes differ, or they are gone, unreadable, or no
longer a regular file. It is best-effort in both directions. Unreadability is noticed only
where a moved timestamp made it read the file at all: a file whose permissions changed and
whose time did not is answered from the time, and it is the next index_directory that
records the failure and takes coverage to "unknown". A path that cannot even be
stat-ed - its parent directory lost its permissions, say - has no timestamp to compare
and is counted straight away. It counts only rows the index
holds, so a file nobody has indexed yet is not among them: finding those means walking the
tree, which is the expensive half of indexing and not something a search should pay for.
And it reads bytes only where the modification time moved, so an edit that restores a file's
own timestamp is missed - indexing is not fooled by that, since it hashes every file it
walks; what is missed is only the hint that running it is worth it. A zero means nothing was
detected, not that every file was re-hashed. coverage stays "verified" while the count is
non-zero: the walk really did finish and really did read every file it found. What moved on
is the tree, and the message says so.
And it carries gitignore: what git said the last time a walk of the root finished -
applied, off (switched off), no_repository (nothing to ignore), unknown (no walk has
recorded it yet: the first search after a start, while the catch-up run is going, or an index
upgraded from a version that did not record it - not a failure, and the run records it), or
unavailable: the root is in a repository git could not be asked about - not installed, timed
out, refused by safe.directory - so what it ignores was indexed as well. Only unavailable
gets a message, and only on a tree that is otherwise whole: it names the git status to run
to see why.
A checkout whose repository is configured bare (core.bare = true, which some agent worktree
tooling sets on the main checkout) makes git refuse with "this operation must be run in a
work tree". The server then asks git again with that checkout as the work tree - what git
itself does once the setting is gone - so .gitignore still applies and worktree routing still
works, and it logs a warning naming git -C <checkout> config core.bare false, which it never
runs for you.
The embedding model
What downloads, when, and where
The first search (or markdown-memory --download-model) fetches three files from
onnx-community/embeddinggemma-300m-ONNX
at a pinned revision: the 4-bit ONNX graph, its external weights, and the tokenizer.
About 218 MB, once per machine, into:
$XDG_CACHE_HOME/markdown-memory/models/embeddinggemma-300m-onnx-5090578d9565/ # ~/.cache/... by default
The revision is part of the folder name, so moving the pin fetches the new weights instead
of serving the old ones under a name that claims to be the new ones. One revision can publish
several graphs, though, so the folder name is not the whole answer: a .verified stamp that
does not name exactly the files this version needs - a cache left behind by the int8 graph at
this same revision, say - is rejected and the files are fetched, rather than half-trusted.
The cache is shared by every project on purpose - the weights are identical and read-only,
so copying them per project would be pure waste. Point MARKDOWN_MEMORY_MODEL_CACHE
somewhere else to move it.
The graph is onnx/model_q4.onnx, published 4-bit: the 262144x768 vocabulary table is
quantized and gathered by a single GatherBlockQuantized, and the projections run as
MatMulNBits, so the table is never expanded to float32. Nothing is derived or rewritten on
your machine - earlier versions ran the int8 graph and patched it here to get the same
effect. Using Gemma is covered by the
Gemma Terms of Use; this repository distributes no
weights.
What is checked before the model is loaded
Every file's size and sha256 is pinned at the pinned revision. After a full check, a
.verified stamp records each file's size, mtime, ctime, inode and device, so an ordinary
start is a handful of stat calls rather than most of a second of hashing. Anything that
differs sends the files back to be hashed against the pins, and a file that does not match
is re-fetched - just that file.
Guaranteed: any change to a model file's contents or metadata since it was verified is
caught. cp -p, tar x and rsync --inplace can overwrite a file and restore its mtime,
which is why ctime is in the stamp - nothing in user space can set that back. Not
guaranteed: silent disk bit-rot, with no write at all.
A failure to load verified files is not treated as damage: it means onnxruntime, permissions or memory, so the error is raised as it stands and nothing is downloaded.
Verification and loading hold a shared flock; downloading and repairing hold it
exclusively, so several servers starting at once download once between them. A model cache
on NFS or SMB shared between machines is not supported - flock can be local-only
there.
Nothing is ever deleted to reclaim space. After a successful start, one log line on stderr
names any other embeddinggemma-300m-onnx* folders and what they cost, and any file sitting
in the current folder that this version does not use - the int8 graph an upgrade left behind
weighs about 310 MB - and removing them is yours to do.
Pre-download it, or install offline
To fetch the model deliberately rather than on the first query:
markdown-memory --download-model # the default, EmbeddingGemma
markdown-memory --download-model --embedder bge-small # or the light preset
It downloads and loads the configured model, then exits; it touches no index.
For a machine with no network, copy the three files into
$XDG_CACHE_HOME/markdown-memory/models/embeddinggemma-300m-onnx-5090578d9565/, keeping
onnx/model_q4.onnx, onnx/model_q4.onnx_data and tokenizer.json where they are. The
first load hashes them once, writes the .verified stamp, and never touches the network.
bge-small is downloaded by fastembed, which pins no revision: if that cache is deleted,
it can come back with different weights under the same model name. EmbeddingGemma's
weights change on purpose, when a release moves its pin or graph. Either way, every document
records the weights that embedded it, and the index records the one revision that vouches
for all of its vectors:
- Indexing repairs in place. A document stamped by other weights is re-embedded like a
changed file, even when its bytes are the same. Before the first new vector is written the
index is marked as being re-embedded; nothing is deleted first, so keyword search answers
throughout, and a run that is killed resumes where it stopped, because each stamp is
written with its vectors. At the end of a run the revision is restored only once no
vector-bearing document in the whole database - every root's, and one indexed on its own
inside a pruned directory such as
.venv- is stamped by anything else. Until thenindex_status.coveragereads"unknown"and its message names the directories still to be indexed. - Searching compares for itself, after embedding the query, and falls back to keyword
ranking alone when the answer differs - for the old weights and the new alike while a
repair is under way. It does not wait to be told: weights can change while no Markdown
file does, and then there is no indexing run to notice. The search that notices records
it, and the next
index_directoryloads the model first and re-embeds what it finds.
A model that loads but cannot say which weights it is may not write into an index that
names its weights: its vectors could never be told apart from the ones already stored. An
index whose vectors no revision vouches for - built while the weights could not be read -
is not ranked against a query from weights that can name themselves - from the upgrade to
schema v6 on - and the first run with such weights re-embeds it. A server that loaded
bge-small while its revision could not be read keeps it unnamed until it restarts: the
revision is read beside the weights it loads, never after them. Nor may a renamed model that
cannot name its weights: indexing refuses, changing nothing, and search ranks by keyword
alone until the old model is back, --db names another file, or the database is rebuilt.
markdown-memory MCP questions
Does this server require an API key or internet connection?
No, it runs entirely on your machine with no API key and no network required after the initial model download.
How does it reduce token usage for coding agents?
Instead of reading whole files, it returns only the specific section or passage that answers the question, significantly reducing context size.
What are the hardware requirements for running the server?
It runs on CPU for Linux or macOS (x86-64 or arm64) and requires roughly 1 GB of disk space.