markdown-memory-mcp
Works with Obsidian-style Markdown vaults, indexing notes, YAML frontmatter, and wikilinks to support semantic recall, hybrid search, backlinks, vault linting, and optional note creation via MCP tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@markdown-memory-mcp search my vault for notes about sourdough starter feeding"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
markdown-memory-mcp
Semantic recall for a Markdown memory vault: a Claude Code hook that brings back the right notes, a linter that keeps the vault healthy, and an MCP server for any MCP client. Local and multilingual.
It works with Obsidian-style vaults: a folder of notes with YAML frontmatter, [[wikilinks]], and an index file such as MEMORY.md that links to the notes.
What you get
Recall hook. A Claude Code
UserPromptSubmithook that adds the notes relevant to each prompt, without the index file having to list them.Search CLI.
markdown-memory-mcp searchranks notes by meaning and by words (BM25 plus embeddings) and shows the score breakdown.Vault linter.
markdown-memory-mcp lintchecks links, frontmatter, duplicates, orphans and index size, with rules VR001 to VR010.MCP server.
markdown-memory-mcp serveexposes search, read, backlinks and lint to any MCP client, and optionally a write tool.
The files stay the source of truth. markdown-memory-mcp never writes to your vault. The only exception is the MCP write_note tool, which exists only if you start the server with --allow-write.
Related MCP server: pkmx
Why
An index file that is loaded into every session has to stay small. As a vault grows, older notes get moved out of the index, and from then on the assistant finds them only when it happens to search for the exact words the note uses. "Keep the starter alive" does not match a note titled "sourdough starter feeding".
markdown-memory-mcp closes that gap in two ways:
Recall by meaning. It ranks notes with BM25 and with embeddings and merges both rankings. The hook injects the few notes that match the current prompt and are not already in the index.
A healthier vault.
markdown-memory-mcp lintfinds broken links, notes without a description, duplicate names, orphans, an index that outgrew its budget, and notes that are near-copies of each other.
How it works
prompt ──▶ UserPromptSubmit hook ──▶ markdown-memory-mcp hook
│
notes (*.md), read on every call ──────┤
│ ▼
│ BM25 (folded, 5-letter stems) ──┐
│ ├─ RRF ─▶ filters ─▶ additionalContext
└─▶ embeddings, cached outside the vault ── cosine ───┘
filters: not linked from an index file, not injected earlier in this session,
cosine >= min_similarity, at most k notesLexical side. Text is Unicode-normalised,
İandIare folded toi, and every word is cut to its first five letters. This crude stemming works well for agglutinative languages such as Turkish. File names count twice, as a cheap title boost.Semantic side. fastembed runs a small model locally (ONNX, no GPU). The default model is multilingual. Queries in the same language as the note work best. Recall across languages, for example an English query for a Turkish note, is weaker. Turkish and other agglutinative text gets most of its help from the folding and prefix stems on the lexical side. Vectors are kept in a cache directory outside the vault and are updated incrementally.
Fusion. Reciprocal Rank Fusion with k = 60 over the two rankings.
search --jsonreturns the score breakdown.Without the
embedextra everything still works on BM25 alone, except the near-duplicate lint rule.
The design, invariants and threat model are in ARCHITECTURE.md.
Requirements
Python 3.11 or later and uv (pip works too).
For embeddings: about 220 MB of disk for the default model, downloaded on the first
index.
Install
uv tool install "markdown-memory-mcp[all] @ git+https://github.com/amercans/markdown-memory-mcp"Extras: embed (fastembed and numpy), mcp (the MCP server), all (both). The core install depends on PyYAML only.
Quick start
The examples run on the small invented vault that ships in the repository. Clone it to follow along:
git clone https://github.com/amercans/markdown-memory-mcp
cd markdown-memory-mcpFor your own vault, use --vault tests/fixtures/vault instead of --vault tests/fixtures/vault. If you run a command from inside the vault, or set MARKDOWN_MEMORY_VAULT, --vault can be left out.
Build the index. The first run downloads the model (about 220 MB, from a public repository, so no Hugging Face token is needed) and shows a download progress bar. Later runs embed only new and changed notes. search, lint, the hook and the server never download anything.
$ markdown-memory-mcp index --vault tests/fixtures/vault
13 notes: 13 added, 0 updated, 0 removed, 0 unchanged (~/.cache/markdown-memory-mcp/<hash>)Search. Neither "keep" nor "alive" appears in the note that comes first:
$ markdown-memory-mcp search "how do I keep the starter alive" --vault tests/fixtures/vault -k 1
1. sourdough-starter-feeding [rrf 0.0328 cosine 0.47 bm25 7.23]
sourdough-starter-feeding.md
How often to feed a sourdough starter and how to revive one that has gone sluggishA Turkish query finds the Turkish note. This hit comes from the lexical side (the stem simit); the cosine is low. It demonstrates folding and stemming, not cross-language recall:
$ markdown-memory-mcp search "simit nasıl yapılır" --vault tests/fixtures/vault -k 1
1. istanbul-simit [rrf 0.0328 cosine 0.13 bm25 3.23]
istanbul-simit.md
İstanbul usulü simit tarifi, pekmezli su ve susam ileLint. The fixture vault contains one deliberate defect for each rule, apart from VR007:
$ markdown-memory-mcp lint --vault tests/fixtures/vault
MEMORY.md
L10 VR002 error index links to missing file retired-vpn-notes.md
L14 VR010 warning line has 244 characters (max 200)
backup-before-migrations-old.md
VR006 info no note or index links here
VR008 warning near-duplicate of backup-before-migrations.md (cosine 0.98)
missing-description.md
L1 VR003 error missing required field 'description'
name-mismatch.md
L1 VR004 warning name 'network-diagram' differs from file name
nginx-cache-headers.md
L11 VR001 error broken wikilink [[nginx-gzip-settings]]
L13 VR009 warning path in code span does not exist: ~/does-not-exist/tool.sh
old-router-firmware.md
VR006 info no note or index links here
raspberry-pi-notes.md
L1 VR004 warning name 'raspberry-pi-setup' differs from file name
L1 VR005 error name 'raspberry-pi-setup' is also used by raspberry-pi-setup.md
raspberry-pi-setup.md
L1 VR005 error name 'raspberry-pi-setup' is also used by raspberry-pi-notes.md
5 errors, 5 warnings, 2 info--json prints the same findings as JSON. --fail-on {error,warning,never} sets the level at which the exit code becomes 1 (default error), so the command can gate a commit or a CI job.
Claude Code hook
Add a UserPromptSubmit hook to the user-level settings.json of Claude Code (in the .claude directory of your home directory):
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{ "type": "command", "command": "markdown-memory-mcp hook --vault ~/notes", "timeout": 10 }
]
}
]
}
}Run markdown-memory-mcp index once first. For the prompt "how do I keep the starter alive" the hook prints:
{"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": "Possibly relevant notes from the memory vault (read before acting if relevant):\n- sourdough-starter-feeding — How often to feed a sourdough starter and how to revive one that has gone sluggish (/path/to/vault/sourdough-starter-feeding.md)"}}The hook is built never to get in the way of a prompt:
It prints nothing for slash commands, prompts shorter than three words, and short acknowledgements such as "ok, thanks".
It does nothing until an index exists. It never downloads a model and never builds an index from scratch.
It updates the index itself only when at most
hook_max_updatesfiles changed. If more changed, it uses the index as it is. Runmarkdown-memory-mcp indexto catch up.It skips notes that an index file already links to, since those are in context anyway, and notes it already injected in the same session.
It applies
min_similarityandrelative_marginto the cosine score, and requires a shared word (BM25 above zero) unless the cosine reachesstrong_similarity.Any error is written as one line to
hook.login the cache directory, and the hook exits 0 without output.
A call takes under a second on the fixture vault, most of it loading the model.
MCP server
markdown-memory-mcp serve speaks MCP over stdio and works with any MCP client. Tools:
Tool | Purpose |
| Hybrid search, with the score breakdown |
| Full text of a note, by file name or frontmatter |
| Notes and index files that link to a note |
| The same findings as |
| Registered only with |
write_note creates <name>.md in the vault root with frontmatter. Names must match ^[a-z0-9](?:[a-z0-9-]{0,79}[a-z0-9])?$ (lowercase letters, digits and inner dashes, 1 to 81 characters). It refuses to overwrite unless overwrite=true, never touches an index file, and refuses paths, symlinks and anything that would land outside the vault.
Claude Desktop, in claude_desktop_config.json. Desktop starts servers with a minimal PATH, so give the absolute path to the executable (the output of which markdown-memory-mcp, for example /path/to/bin/markdown-memory-mcp) and a vault path without ~:
{
"mcpServers": {
"markdown-memory-mcp": {
"command": "/path/to/bin/markdown-memory-mcp",
"args": ["serve", "--vault", "/path/to/vault"]
}
}
}Claude Code:
claude mcp add markdown-memory-mcp -- markdown-memory-mcp serve --vault ~/notesAppend --allow-write to the arguments to expose write_note.
Lint rules
Code | Level | Check |
VR001 | error | Broken |
VR002 | error | An index file links to a local |
VR003 | error | No frontmatter, frontmatter that is not a valid YAML mapping, or a field from |
VR004 | warning | Frontmatter |
VR005 | error | Two notes use the same |
VR006 | info | Orphan: no note and no index file links to it. |
VR007 | warning / error | An index file is over |
VR008 | warning | Near-duplicate notes (cosine at or above |
VR009 | warning | A path in backticks does not exist. Paths starting with |
VR010 | warning | An index line is longer than |
Configuration
The vault is taken from --vault, then $MARKDOWN_MEMORY_VAULT, then the current directory. Settings come from --config, or from .markdown-memory.toml in the vault root. Every key is optional:
index_files = ["MEMORY.md"]
exclude = [".obsidian/**", ".trash/**"]
lint_exclude = []
model = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
k = 3
min_similarity = 0.30
relative_margin = 0.08
strong_similarity = 0.55
required_fields = ["name", "description"]
max_index_line = 200
hook_max_updates = 20
duplicate_similarity = 0.92
[index_budget_bytes]
soft = 13000
hard = 15000Key | Default | Meaning |
|
| Index files, relative to the vault. They are linted as indexes and not searched, and what they link to counts as already in context. |
|
| Glob patterns, relative to the vault, for files to ignore. Setting it replaces the default. |
|
| Glob patterns for files that |
|
| A multilingual model that fastembed supports, for example |
|
| Results for |
|
| Minimum cosine for the hook to inject a note. Without embeddings, any BM25 match counts. |
|
| The hook injects a note only if its cosine is within this distance of the best cosine over all notes, including notes it skips because an index file already links them. If the best match is already in context, weaker notes are not used as filler. |
|
| A note that shares no word with the prompt (BM25 score 0) is injected only if its cosine reaches this value. Notes with a lexical match need only pass |
|
| Frontmatter fields checked by VR003. |
|
| Size limits for index files, checked by VR007. |
|
| Longest allowed index line, checked by VR010. |
|
| Most changed files the hook re-embeds on its own. |
|
| Cosine at which VR008 reports a pair. |
MARKDOWN_MEMORY_CACHE sets the cache directory. Otherwise it is $XDG_CACHE_HOME/markdown-memory-mcp or ~/.cache/markdown-memory-mcp. Each vault and model pair gets its own subdirectory, and the downloaded models live in models/ next to them.
This project was called vault-recall before 0.2.0. The old config file name .vault-recall.toml is still read for this release, with a one-line note on stderr, when .markdown-memory.toml does not exist. An existing vault-recall cache directory is moved to the new name on first use, so the model is not downloaded again. The VAULT_RECALL_* environment variables are no longer read; use MARKDOWN_MEMORY_VAULT and MARKDOWN_MEMORY_CACHE.
Privacy
Everything runs on your machine. The only network access is the one-time download of the embedding model from Hugging Face, the first time you run markdown-memory-mcp index. After that nothing leaves the machine: no telemetry and no calls to a hosted API. The index lives in the cache directory, never inside the vault. It holds the vectors and, in meta.json, the model name, the absolute path of the vault, and each note's relative file name, modification time and hash. It holds no note text. The cache directories it creates are mode 0700 and its files 0600.
Limitations
The index is one array that is read whole. That suits thousands of notes, not hundreds of thousands.
The vault is read on every hook call. There is no daemon, so each call pays for Python start-up and for loading the model.
Five-letter stemming is a heuristic. It merges unrelated words that share a prefix and splits related words that do not.
Without the
embedextra the hook falls back to BM25,min_similaritydoes not apply, and it injects more loosely related notes.Files over 1 MB are skipped. Only Markdown is read.
Embeddings are computed from the title,
name,descriptionand the first 3000 characters of a note.VR009 cannot tell a URL route from a file path when the route's first segment is also a directory on your machine, such as
/usr/...or/opt/....The
mcpextra is pinned below 2.0, because the server uses the FastMCP interface of the 1.x SDK.
Development
uv sync --all-extras
uv run ruff check . && uv run ruff format --check .
uv run pytest # no model download; uses a deterministic hashing embedder
uv run pytest -m slow # also runs the real model
git config core.hooksPath tools/hooks # run tools/leak-scan.sh before every pushSee CONTRIBUTING.md.
License
Available Tools
4 toolsbacklinksA
List the notes and index files that link to a note, by [[wikilink]] or Markdown link.
Args:
name: The note's file name without .md, or its frontmatter name.
Returns a list of {name, path, line}. Empty if nothing links to it.
Inputs: name (required). Returns: result
lint_vaultA
Check the vault for broken links, missing frontmatter, duplicate names, orphans and an oversized index. Takes no arguments.
Returns {findings: [{code, level, path, line, message}]}. Codes VR001-VR010.
Inputs: no named parameters.
read_noteA
Read one note in full.
Args:
name: The note's file name without .md, or its frontmatter name. Paths are
refused.
Returns {name, path, description, content}, where content is the whole file.
Inputs: name (required).
search_notesA
Find notes by meaning and by words. Use this to recall what the vault knows.
Args: query: What to look for, in natural language. k: How many notes to return (1-50).
Returns a list, best first, of {name, path, description, rrf, cosine, bm25}. path is
relative to the vault; pass name to read_note for the full text. cosine is null
when the note has no embedding yet.
Inputs: query (required), k. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a clearly distinct operation: semantic/keyword retrieval (search_notes), full-text retrieval by name (read_note), link-graph inspection (backlinks), and vault health checking (lint_vault). There is no overlap — search vs. read is a natural retrieve-then-expand split, and backlinks/lint are separate concerns entirely.
Three of four tools follow a clean verb_noun snake_case pattern (search_notes, read_note, lint_vault). 'backlinks' breaks the pattern as a bare noun, a minor but noticeable deviation.
Four tools is lean but each one earns its place in a read/retrieve workflow. It sits just under the comfortable range, so the surface feels slightly minimal rather than over-scoped.
The surface is read-only: there is no way to create, update, or delete a note, and no listing/enumeration of the vault. For a 'memory' server, the inability to write a memory is a significant gap that will force agents to fail on store/update workflows.
Maintenance
Related MCP Connectors
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Related MCP Servers
- AlicenseAqualityBmaintenanceLocal MCP server for querying and maintaining a Markdown vault. Provides full-text search, backlinks, note retrieval, and optional confined write tools, without sending the whole vault to the client context.22110 PyPI1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceExposes a local Markdown vault to AI agents over stdio, letting them search, read, create, update (with mtime-guarded writes), and append notes, as well as list and manage saved views. Write permissions can be toggled per group in settings, and all changes land as plain Markdown/YAML files in the chosen folder.MIT
- AlicenseNot gradedqualityFmaintenanceExposes a stdio MCP server that indexes a markdown vault (such as an Obsidian folder of notes) into SQLite FTS5 and answers BM25-ranked section-level queries, with filters for note type. It also exposes reindexing so notes edited on disk become searchable again, giving coding agents persistent, durable memory across sessions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search and manage a local Markdown memory vault over stdio, including hybrid search, note retrieval and addition, session handoff claiming, and status checks without holding a model in memory.MIT