Skip to main content
Glama

kb-mcp — a personal knowledge-base MCP server

An MCP server that gives an AI assistant a long-term memory you control: save notes and bookmarks, import folders and web pages, find anything with hybrid search, and let the assistant remember what it learns about you across conversations. It is built from scratch on the official MCP Python SDK (v2), with SQLite storage, a local embedding model (no API key, nothing leaves your machine), and tests at the protocol level.

Status: all five phases complete: MCP fundamentals, semantic search, hybrid search + evaluation, ingestion pipeline, agent memory. See the roadmap.

What the assistant gets

Tools. Every tool declares annotations so clients can auto-approve reads and confirm destructive calls. Every tool returns typed, schema-checked output.

Tool

Does

Annotations

search_notes(query, tag?, limit?, mode?)

hybrid (default): keyword + semantic fused with Reciprocal Rank Fusion, optionally re-ranked. semantic: meaning only. keyword: exact words, BM25.

read-only

find_similar(note_id, limit?)

Notes closest in meaning to a given note

read-only

get_note(note_id)

One note in full

read-only

list_notes(tag?, limit?, offset?)

Recent notes, paginated with next_offset

read-only

list_tags()

Tags with counts

read-only

add_note(title, body?, tags?)

Save a note

write

save_bookmark(url, title, notes?, tags?)

Save a link (http/https only)

write

update_note(note_id, title?, body?, tags?)

Change only the fields given

write, idempotent

delete_note(note_id)

Permanent delete

destructive

import_url(url, tags?)

Fetch a web page, keep its readable text, save it as a note; re-importing refreshes it

write, idempotent, open-world

import_history(limit?)

Recent import runs with counts and errors

read-only

remember(content, kind?, importance?, supersedes?, force?)

Keep a fact about the user. Similar existing memories are returned for review instead of being duplicated or overwritten

write

recall(query?, kinds?, limit?)

Memories ranked by relevance × importance × recency

read-only

list_memories(kinds?, include_superseded?)

Everything remembered

read-only

review_memories()

Possible duplicates and stale minor memories (changes nothing)

read-only

forget(memory_id)

Delete a memory and its earlier versions

destructive

Resources, which the user or client can attach as context:

  • kb://notes/{note_id}: a note rendered as Markdown

  • kb://tags: every tag with its note count

  • kb://stats: counts of notes, bookmarks and tags

  • kb://imports: the last 20 import runs

  • kb://memories: everything remembered, grouped by kind

Prompts, as reusable workflows:

  • summarize_tag(tag): summarise everything under a topic, with citations

  • find_related(note_id): have the model search for connected notes and explain the links

  • start_with_memory(topic?): open a conversation by recalling relevant memories

Related MCP server: NoteKeeper MCP

How semantic search works

  1. Chunk. Each note is split into overlapping ~180-word passages, each prefixed with the note's title. Short notes stay as one chunk. This keeps a long note's different topics from blurring into one vector.

  2. Embed. Each chunk goes through BAAI/bge-small-en-v1.5, a 384-dimensional model of about 70 MB, run locally with ONNX Runtime via fastembed. Vectors are L2-normalised.

  3. Store. Vectors live in SQLite next to the notes (note_chunks), tagged with the model name and a hash of the note's content.

  4. Search. The query is embedded, scored against every chunk with one matrix multiplication (cosine similarity), and each note is ranked by its best chunk.

Engineering choices:

  • Brute-force search, on purpose. A personal knowledge base has thousands of chunks, not millions. Exact search over a NumPy matrix takes about a millisecond and is never wrong, so an approximate index (FAISS, HNSW) would add complexity for no gain at this scale. The store has a single place to swap one in.

  • Always consistent. Notes are re-embedded when saved or edited. A content hash and the model name detect anything stale, including notes saved before Phase 2 existed or after a model change, and fix it before searching.

  • Fails soft. If the model can't load (for example, offline on first run), saving still works, and search falls back to keyword mode with a notice saying so, rather than erroring.

How hybrid search works (Phase 3)

Keyword and semantic search fail in opposite places:

  • Embeddings blur codes and identifiers. 23505, B905 and HEAD@{2} carry almost no meaning.

  • Keyword search misses anything phrased differently.

Hybrid search runs both and merges them:

  1. Two candidate lists. BM25 in any-term mode (any word may match, so it finds more candidates) and semantic search each return their top 30.

  2. Reciprocal Rank Fusion. Each note scores Σ 1/(60 + rank) across the two lists. RRF uses ranks, not raw scores, so BM25 and cosine similarity never need calibrating against each other. A note found by both lists rises highest.

  3. Optional re-ranking (kb-mcp --rerank). A cross-encoder (ms-marco-MiniLM-L-6-v2, about 80 MB, local) reads the query and each of the top 20 candidates together and re-orders them. It is more accurate than comparing vectors and much slower, so it only touches the shortlist.

Every step fails soft:

  • No embedding model: keyword results, with a notice.

  • No re-ranker: fused results, with a notice.

Measuring it

kb-mcp eval loads a hand-labelled set (eval_data.json: 52 notes, 60 queries) into a throwaway store and scores every mode on recall@5, MRR, nDCG@5 and latency. The queries are deliberately mixed so no single method can look perfect:

Query type

n

Example

Hard for

paraphrase

31

"my container keeps getting killed" → the exit-code-137 note

keyword

exact

7

"XCom"

—

identifier

11

"23505", "B905", "0 6 * * 1-5"

embeddings

fine-grained

11

"why did old messages disappear from my topic" among four near-identical Kafka notes

both

Results (MacBook Air, Apple Silicon; MRR = how often the right note comes first, 1.0 = always):

Query type

n

keyword

semantic

hybrid (default)

hybrid + re-rank

paraphrase

31

0.00

0.91

0.85

0.87

exact

7

1.00

1.00

1.00

1.00

identifier

11

1.00

1.00

1.00

1.00

fine-grained

11

0.00

0.79

0.85

0.88

all (MRR)

60

0.30

0.92

0.90

0.91

all (recall@5)

60

0.30

0.97

0.97

0.97

all (nDCG@5)

60

0.30

0.92

0.91

0.92

median latency

0.1 ms

2.5 ms

2.7 ms

79 ms

What the evaluation changed

  • The first version of hybrid search was worse than semantic alone (MRR 0.88 vs 0.92, and 0.82 vs 0.91 on paraphrases). Its misses pointed to the cause: in a small corpus, function words like "my" and "how" are rare, so BM25 gave them high weight, and "my query ran out of RAM" matched notes that happened to contain "my". Dropping stopwords from the keyword half raised hybrid to recall@5 0.97 and MRR 0.90. A test now guards against the regression.

  • Down-weighting the keyword list (0.5×) changed nothing, so the problem was noisy keyword candidates, not the fusion weights.

Conclusions

  • Semantic and hybrid are statistically tied. The 0.02 MRR gap is about one query out of 60. Each wins where you'd expect: semantic on paraphrases, hybrid on near-duplicates.

  • Hybrid stays the default. It equals semantic on recall, is better at telling near-identical notes apart, and keeps an exact-match path for codes in a larger, messier notebook. In this set the embeddings happened to handle every identifier anyway.

  • Re-ranking is optional (--rerank). It is the best mode on near-duplicates (recall@5 1.00, MRR 0.88) but about 30× slower and no better overall.

  • Caveat: 60 hand-written queries is small, and the dataset was extended while this phase was being built. Treat these as directional, not definitive.

Ingestion pipeline (Phase 4)

Bring in what you already have, and keep it in sync:

kb-mcp ingest folder ~/Notes            # Markdown / .txt (an Obsidian vault works as-is)
kb-mcp ingest folder ~/Notes --prune    # ...and remove notes whose file was deleted
kb-mcp ingest bookmarks ~/Downloads/bookmarks.html   # browser export: Chrome, Safari, Firefox, Edge
kb-mcp ingest url https://example.com/article --tag reading
kb-mcp runs                             # what each run added, updated, skipped or failed

Source

Title

Tags

Identity (for re-runs)

Folder

front matter title: → first # heading → file name

front matter tags: + inline #hashtags

folder + relative path

Bookmarks

link text

bookmark folder names (browser root folders skipped)

normalised URL

Web page

<title>

given with --tag

normalised final URL

How the pipeline is built:

  • Idempotent. Each imported note is tracked by (source type, source id) with a content hash. A re-run updates only what changed and skips the rest. Unchanged items cost nothing, not even re-embedding.

  • No duplicates. URLs are normalised: lower-case host, no #fragment, no utm_*/fbclid tracking parameters, no trailing slash. A bookmark for a page you already saved by hand is linked to your note instead of copied, and your note is left untouched.

  • Safe deletes. --prune is opt-in and only removes notes that came from that folder. It never touches hand-written notes or other sources.

  • Partial failure is normal. A bad file or a page that times out is counted and logged, and the run continues. Every run is recorded in ingest_runs and exposed through import_history and kb://imports.

  • SSRF-safe fetching. import_url can be called by the model, so a prompt-injected page could try to make the server fetch localhost, a router or a cloud metadata endpoint. The fetcher therefore:

    • allows only http(s)

    • resolves the hostname and refuses non-public addresses, re-checking after every redirect

    • caps pages at 2 MB with a 15-second timeout

    • accepts only HTML or plain text

    Folder and bookmark imports stay CLI-only, so the model can never read arbitrary files from your disk.

  • Readable text only. Scripts, styles, navigation, headers, footers and sidebars are dropped. <article>/<main> is preferred when it holds real content.

Keeping a folder in sync automatically (macOS/Linux cron, every morning at 7:45):

crontab -e
45 7 * * * /ABSOLUTE/PATH/TO/.venv/bin/kb-mcp ingest folder ~/Notes --prune >> ~/.kb-mcp/ingest.log 2>&1

Agent memory (Phase 5)

Notes are documents you choose to save. Memories are short facts the assistant picks up on its own while you talk ("prefers concise answers", "applying for data engineering roles", "decided on DuckDB over Postgres"), so the next conversation starts with that context.

Ranking. Recall combines three signals, following the recency × importance × relevance idea from Generative Agents (Park et al., 2023):

score = 0.6 × relevance  +  0.25 × importance/5  +  0.15 × 0.5^(age_days / 30)
  • relevance is the cosine similarity to the current topic. With no topic, everything counts as relevant, so "what do you know about me?" returns the most important and recent memories.

  • importance (1–5) is set by the assistant when it saves the memory.

  • recency halves every 30 days since the memory was last confirmed.

Memories are never silently rewritten, and embeddings never decide what counts as "the same". The first design merged any new memory with cosine ≥ 0.92 to an existing one. Measuring that threshold on the real model (kb-mcp eval --memory) showed the idea itself was wrong, not just the number:

Pair

Relation

Cosine

"Applying for data engineering jobs" / "Is job hunting for data engineer roles"

same fact

0.880

"Lives in Virginia" / "Lives in Maryland"

conflict

0.827

"Prefers concise answers" / "Likes short, concise replies"

same fact

0.819

"Uses DuckDB for analytics" / "Uses Postgres for analytics"

conflict

0.815

"Prefers concise answers" / "Prefers detailed explanations"

conflict

0.798

"Uses Python for most projects" / "Writes most of their code in Python"

same fact

0.783

"Working on the NBA data platform" / "Working on the Olist delivery project"

unrelated

0.634

"Has a dog named Max" / "Likes hiking on weekends"

unrelated

0.435

Rewordings of one fact (0.78–0.88) and contradictory facts (0.80–0.83) overlap completely, so any merge threshold either duplicates memories or silently overwrites "Maryland" with "Virginia". The design was changed so that:

  • Only identical text (ignoring case and spacing, same kind) is merged automatically.

  • Anything similar (cosine ≥ 0.75) is not saved. remember returns needs_review with the similar memories, and the assistant, which understands the sentences, decides. If it's the same fact, it does nothing. If the fact changed, it calls remember(..., supersedes=<id>), which keeps the old version as history but hides it from recall. If it's a different fact, it calls remember(..., force=true).

  • At 0.75, every same-fact and conflicting pair above is surfaced for review, and both unrelated pairs are saved directly.

  • review_memories uses the same threshold to list possible duplicates and stale minor memories. It deletes nothing itself.

Privacy and control:

  • Memories live in the same local SQLite file as the notes.

  • The server instructions tell the assistant not to store secrets, credentials or sensitive personal details unless asked.

  • forget deletes a memory together with its history.

  • kb-mcp memories lists everything, and kb-mcp memories --export memories.json exports it.

Design decisions

  • The storage layer knows nothing about MCP. store.py is plain Python + SQLite, and server.py is a thin protocol layer over it. Later phases (vector search, ingestion) plug in behind the same interface.

  • Errors are part of the contract. An unknown id, a bad URL or an invalid tag raises ToolError, so the model gets an actionable message ("No note with id 999. Use search_notes…"), not a stack trace. Missing resources return a proper ResourceNotFound protocol error.

  • Search is injection-proof. User text is tokenised and quoted before it reaches FTS5, so stray quotes or AND/OR/NEAR can never break or alter the query. This is tested.

  • The full-text index stays consistent by construction. It is an external-content FTS5 table kept in sync by triggers, so updates and deletes can't leave stale search results.

  • Two transports:

    • stdio, for Claude Desktop and other local clients

    • Streamable HTTP (--http), for remote or multi-client use

Install and run

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                         # 90 tests: storage, search, ingestion, memory, protocol, real stdio round-trip
kb-mcp reindex                 # one-time: downloads the embedding model and embeds existing notes
kb-mcp eval                    # keyword vs semantic vs hybrid vs re-ranked, by query type
kb-mcp --rerank                # serve with cross-encoder re-ranking on
kb-mcp --db ~/.kb-mcp/kb.db    # stdio
kb-mcp --http --port 8765      # Streamable HTTP at http://127.0.0.1:8765/mcp

Use it from Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), using the absolute path to the kb-mcp script in your virtualenv:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/kb-mcp",
      "args": ["--db", "/Users/YOU/.kb-mcp/kb.db"]
    }
  }
}

Restart Claude Desktop, then try "save a note that DuckDB's union_by_name opens every file at once" and "what have I saved about DuckDB?"

Inspect it

npx @modelcontextprotocol/inspector .venv/bin/kb-mcp

Tests

File

What it proves

tests/test_store.py

CRUD, tag normalisation, BM25 ranking (title > body), prefix search, index consistency after update and delete, FTS-syntax safety, persistence

tests/test_semantic.py

Chunking, embedding on write, staleness after edits and model changes, legacy-database backfill, best-chunk ranking, tag filter, similarity, failure never losing a write, RRF fusion, identifier rescue, re-ranking, eval harness and dataset integrity

tests/test_ingest.py

Folder parsing (front matter, headings, hashtags, hidden folders), idempotent re-runs, change detection with re-embedding, scoped prune, per-item failures, bookmark parsing, URL normalisation and dedup, readable-text extraction, SSRF guard

tests/test_memory.py

Validation, identical-text merging, needs-review for similar memories, force and supersede paths, supersede history, relevance/importance/recency ranking with a fake clock, filtering irrelevant memories, forgetting whole chains, review, no-model fallback, persistence, export, tools end to end

tests/test_server.py

Through a real MCP client (in-process): tool schemas and annotations, structured output, error contract, input validation, pagination, resources, prompts, search modes, fallback notices

tests/test_stdio.py

The server launched as a subprocess over stdio, the way Claude Desktop runs it

Roadmap

Phase

Adds

Status

1. MCP fundamentals

Tools, resources, prompts, annotations, structured output, stdio + HTTP

✅

2. Semantic search

Local embeddings, chunking, vector search, find_similar, retrieval eval

✅

3. Hybrid search

BM25 + vectors with RRF, cross-encoder re-ranking, harder evaluation (identifier and near-duplicate queries)

✅

4. Ingestion pipeline

Folders, bookmark exports, web pages; idempotent upserts, URL dedup, scoped prune, run log, SSRF-safe fetching

✅

5. Agent memory

Memories the assistant writes itself: model-judged dedup and supersede, recency × importance × relevance recall, review, forget, export

✅

Layout

src/kb_mcp/store.py        SQLite storage: notes, FTS5 keyword index, embeddings (no MCP dependency)
src/kb_mcp/embeddings.py   embedding + re-ranking models (local fastembed, offline test doubles) and chunking
src/kb_mcp/memory.py       agent memory: remember / recall / supersede / review / forget
src/kb_mcp/ingest.py       ingestion: folder, bookmarks and web sources, the idempotent pipeline, SSRF guard
src/kb_mcp/evaluate.py     retrieval evaluation (recall@5, MRR, nDCG@5, latency) on eval_data.json
src/kb_mcp/server.py       MCP tools, resources, prompts, CLI entry point
tests/                 storage, protocol and stdio tests

Available Tools

8 tools
add_noteAdd noteC

Save a new note.

Inputs: title (required), body, tags. Returns: id, uri, url, body, +4 more

delete_noteDelete noteB
Destructive

Permanently delete a note or bookmark. Confirm with the user first.

Inputs: note_id (required). Returns: id, title, deleted

get_noteGet noteA
Read-onlyIdempotent

Fetch one note or bookmark in full.

Inputs: note_id (required). Returns: id, uri, url, body, +4 more

list_notesList notesA
Read-onlyIdempotent

List notes, most recently updated first. Paginate with offset / next_offset.

Inputs: tag, limit, offset. Returns: notes, total, next_offset

list_tagsList tagsB
Read-onlyIdempotent

All tags in use, with how many notes carry each.

Inputs: no named parameters. Returns: result

save_bookmarkSave bookmarkB

Save a link with a title and optional notes.

Inputs: url (required), title (required), tags, notes. Returns: id, uri, url, body, +4 more

search_notesSearch notesB
Read-onlyIdempotent

Full-text search over notes and bookmarks, best matches first.

Inputs: query (required), tag, limit. Returns: hits, query

update_noteUpdate noteA
Idempotent

Change a note's title, body or tags. Fields left out stay as they are.

Inputs: note_id (required), body, tags, title. Returns: id, uri, url, body, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (list/search/get/add/update/delete), and the descriptions distinguish search_notes from list_notes well. The main ambiguity is the note/bookmark boundary: get_note and delete_note operate on 'note or bookmark', but creation splits into add_note vs save_bookmark, and it's unclear whether update_note applies to bookmarks.

    Naming Consistency4/5

    Names follow a predictable verb_noun snake_case pattern (list_tags, search_notes, get_note, update_note, delete_note). The only deviation is the create pair using different verbs, add_note vs save_bookmark, which adds mild inconsistency to an otherwise uniform set.

    Tool Count5/5

    Eight tools is well-scoped for a knowledge-base server: list/search/read, two create paths, update, delete, and tag listing. Each tool earns its place and no tool looks like filler.

    Completeness4/5

    Note lifecycle is fully covered (create, read, list, search, update, delete) and tags can be set via update_note and enumerated via list_tags. The gap is bookmarks: there is no way to update a bookmark's URL/title/tags, and update_note is described only for notes, leaving bookmark maintenance a dead end.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage a personal markdown-based knowledge base with natural language interactions. Supports creating, searching, updating, and organizing notes across categories like people, recipes, meetings, and procedures.
      11
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with tools to create, list, search, tag, and delete notes stored in a local SQLite database.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to capture bookmarks, sticky notes, todos, notes, and web archives, and to search and organize personal knowledge and memory across cloud-synced clients.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to search, read, and navigate a folder of Markdown notes as a knowledge base, with full-text search, backlinks, tags, metadata, and note resources for conversation attachment.
      1
      MIT