Skip to main content
Glama
markdown-memory-mcp

markdown-memory-mcp

by amercans

markdown-memory-mcp

CI OpenSSF Scorecard Release License: MIT

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 UserPromptSubmit hook that adds the notes relevant to each prompt, without the index file having to list them.

  • Search CLI. markdown-memory-mcp search ranks notes by meaning and by words (BM25 plus embeddings) and shows the score breakdown.

  • Vault linter. markdown-memory-mcp lint checks links, frontmatter, duplicates, orphans and index size, with rules VR001 to VR010.

  • MCP server. markdown-memory-mcp serve exposes 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 lint finds 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 notes
  • Lexical side. Text is Unicode-normalised, İ and I are folded to i, 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 --json returns the score breakdown.

  • Without the embed extra 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-mcp

For 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 sluggish

A 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 ile

Lint. 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_updates files changed. If more changed, it uses the index as it is. Run markdown-memory-mcp index to 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_similarity and relative_margin to the cosine score, and requires a shared word (BM25 above zero) unless the cosine reaches strong_similarity.

  • Any error is written as one line to hook.log in 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

search_notes(query, k=5)

Hybrid search, with the score breakdown

read_note(name)

Full text of a note, by file name or frontmatter name

backlinks(name)

Notes and index files that link to a note

lint_vault()

The same findings as markdown-memory-mcp lint

write_note(name, description, body, type=None, overwrite=False)

Registered only with --allow-write

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 ~/notes

Append --allow-write to the arguments to expose write_note.

Lint rules

Code

Level

Check

VR001

error

Broken [[wikilink]]. A link resolves by file name or by frontmatter name; |alias and #heading are ignored. Links in code are ignored.

VR002

error

An index file links to a local .md file that does not exist.

VR003

error

No frontmatter, frontmatter that is not a valid YAML mapping, or a field from required_fields that is missing or empty.

VR004

warning

Frontmatter name differs from the file name.

VR005

error

Two notes use the same name.

VR006

info

Orphan: no note and no index file links to it.

VR007

warning / error

An index file is over index_budget_bytes.soft (warning) or .hard (error).

VR008

warning

Near-duplicate notes (cosine at or above duplicate_similarity). Needs the embedding index and is skipped without it.

VR009

warning

A path in backticks does not exist. Paths starting with ~/ are always checked. An absolute path is checked only if its first directory exists on this machine (/Users, /etc, /opt); otherwise it is taken for a URL route and skipped, as are paths with [, *, <, {, … or ..., and paths with a YYYY, MM, DD or XXX placeholder.

VR010

warning

An index line is longer than max_index_line characters.

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 = 15000

Key

Default

Meaning

index_files

["MEMORY.md"]

Index files, relative to the vault. They are linted as indexes and not searched, and what they link to counts as already in context.

exclude

[".obsidian/**", ".trash/**"]

Glob patterns, relative to the vault, for files to ignore. Setting it replaces the default.

lint_exclude

[]

Glob patterns for files that lint does not report on, in addition to exclude. They are still searched and still count as link sources and targets. Useful for backup or archive folders.

model

sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

A multilingual model that fastembed supports, for example minishlab/potion-multilingual-128M. Changing it builds a new index.

k

3

Results for search and the hook.

min_similarity

0.30

Minimum cosine for the hook to inject a note. Without embeddings, any BM25 match counts.

relative_margin

0.08

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.

strong_similarity

0.55

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 min_similarity and relative_margin.

required_fields

["name", "description"]

Frontmatter fields checked by VR003.

index_budget_bytes

soft = 13000, hard = 15000

Size limits for index files, checked by VR007.

max_index_line

200

Longest allowed index line, checked by VR010.

hook_max_updates

20

Most changed files the hook re-embeds on its own.

duplicate_similarity

0.92

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 embed extra the hook falls back to BM25, min_similarity does 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, description and 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 mcp extra 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 push

See CONTRIBUTING.md.

License

MIT

Available Tools

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

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Local 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.
      22
      110 PyPI
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 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
    • A
      license
      Not graded
      quality
      F
      maintenance
      Exposes 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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