Provides persistent Markdown-based memory for AI agents with full-text and semantic search capabilities.
Also known as Kyrzin/kybase, kybase-mcp
- Stars
- 6
- Tools
- 18
- Downloads, 30 days
- —
- Latest version
- 0.2.4
- Last commit
- Nov 13, 2026
- License
- AGPL-3.0
What is Kybase MCP?
Kybase provides persistent Markdown-based memory for AI agents with full-text and semantic search capabilities. It exposes 18 tools, such as list_notes, get_note, create_note.
Summary generated from the project's README
About Kybase MCP server
Kybase provides a persistent memory layer for AI agents using Markdown-based notes. It operates as a local MCP server via stdio, meaning it requires no separate database installation or Docker setup. The server creates a local knowledge base in a hidden directory on your machine and uses an embedded Postgres instance to manage data. Developers can connect it to clients like Claude Desktop, Claude Code, or Cursor by adding it to their configuration files.
This tool offers 18 different tools for reading, writing, searching, and linking notes. While full-text search works immediately in English and Russian, semantic search requires an embedding provider. You can use local options like Ollama or cloud services such as Google or OpenAI. If you choose a cloud provider, your note text is sent to that service, but otherwise, everything stays on your machine. The system is designed to be compatible with the full Kybase web application, allowing you to export your entire vault as a zip file or import it later.
What you can do with it
- 1Store agent knowledgeInstruct an AI agent to save specific information into its long-term Markdown memory.
- 2Perform semantic searchesAsk an AI to find relevant notes based on meaning rather than just keyword matching.
- 3Connect multiple local agentsAllow different AI tools running on the same computer to share a single knowledge base.
Written from the project's README. Every use case is checked against a quote from it.
How to install Kybase MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Kybase MCP in Claude Code
$ claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'GOOGLE_API_KEY=<YOUR_GOOGLE_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' kybase -- npx -y kybase-mcpInstall Kybase MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"kybase": {
"command": "npx",
"args": [
"-y",
"kybase-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"GOOGLE_API_KEY": "<YOUR_GOOGLE_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install Kybase MCP in VS Code
.vscode/mcp.json
{
"servers": {
"kybase": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"kybase-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"GOOGLE_API_KEY": "<YOUR_GOOGLE_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install Kybase MCP in VS Code CLI
$ code --add-mcp '{"name":"kybase","type":"stdio","command":"npx","args":["-y","kybase-mcp"],"env":{"DATABASE_URL":"<YOUR_DATABASE_URL>","GOOGLE_API_KEY":"<YOUR_GOOGLE_API_KEY>","OPENAI_API_KEY":"<YOUR_OPENAI_API_KEY>"}}'Install Kybase MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"kybase": {
"command": "npx",
"args": [
"-y",
"kybase-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"GOOGLE_API_KEY": "<YOUR_GOOGLE_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install Kybase MCP in Codex
$ codex mcp add kybase --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'GOOGLE_API_KEY=<YOUR_GOOGLE_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' -- npx -y kybase-mcpInstall Kybase MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.kybase] command = "npx" args = ["-y", "kybase-mcp"] [mcp_servers.kybase.env] DATABASE_URL = "<YOUR_DATABASE_URL>" GOOGLE_API_KEY = "<YOUR_GOOGLE_API_KEY>" OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
Install Kybase MCP in Gemini CLI
$ gemini mcp add -s user -e 'DATABASE_URL=<YOUR_DATABASE_URL>' -e 'GOOGLE_API_KEY=<YOUR_GOOGLE_API_KEY>' -e 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' kybase npx -- -y kybase-mcpInstall Kybase MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"kybase": {
"command": "npx",
"args": [
"-y",
"kybase-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>",
"GOOGLE_API_KEY": "<YOUR_GOOGLE_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for kybase-mcp 0.2.4 in an isolated container with no network and no keys. It answered and listed 18 tools.
Kybase MCP tools 18
Read from the server with tools/listlist_notesList notes newest first, filtered by folder, tag or date. This is the tool for "what is new" and "what changed lately": search_notes ranks by relevance and never by recency. created_* is when a note was made, updated_* when its own text last changed — a rename elsewhere rewriting a [[link]] inside it does not count as an edit here. Each row carries content_length, so you can tell a long note from a short one before spending a get_note call. With trashed:true the other filters are ignored.
get_noteRead one note, by id or title. - Long notes come back windowed — 20000 chars by default: check `content_truncated` and pass `next_offset` back as `offset` for the rest. A windowed reply carries `headings` — the H1–H3 outline with character offsets — so name one in `section` to get that heading and its body alone instead of paging through the note. - `resolve_links:true` also returns the notes this one links to, id/title only unless you add include_content:true, whose text is capped at 4000 chars — call get_note on an id for the whole of one. Targets that match no note are listed as unresolved. - Pass the `updated_at` you read back as `expected_updated_at` when you write. `content_updated_at` is the one that moves only on a real edit to this note: a rename elsewhere rewriting a [[link]] inside it touches `updated_at` but not that.
create_noteCreate a new note. Embedding is generated automatically in the background. The server instructions' wikilink and tag rules apply: search_notes for the topic first and link the related notes it finds, and call list_tags before coining a new tag.
update_noteUpdate note fields. Re-embeds if title or content changed. Updates wikilinks if title changed. The server instructions' wikilink and tag rules apply when substantially rewriting — in particular, call list_tags before coining a new tag. Pass expected_updated_at (the updated_at you read) to be refused instead of overwriting a change made in between.
append_to_noteAdd text to a note without resending the rest — prefer it over update_note for journals, logs and running lists. A blank line separates your text from what was there. The note is locked for the read-modify-write, so two sessions appending at the same moment keep both additions instead of the later one overwriting the earlier. Re-embeds in the background like any content change.
replace_in_noteReplace exact text in a note without resending the rest. Either find/replace or old_string/new_string — the same pair, either spelling. For several replacements pass `edits` rather than the singular fields (one lock and one re-embed for the batch, not one per call); the two forms cannot be combined in one call. Edits apply in order, and each `find` is matched against the note as the edits before it already changed it — an earlier edit can create the text a later one needs, or destroy it, so sequence them. If any step's count is wrong the whole batch is refused and the note is left untouched, and the error names the failing index.
delete_noteSoft-delete a note by id — it disappears from list_notes/search/get_note/the graph, but is recoverable with restore_note for 30 days before being purged for good. Use list_notes with trashed:true to see what's currently in the trash.
restore_noteUndo delete_note: brings a soft-deleted note back. Errors if the note isn't in the trash (never deleted, already restored, or purged past the retention window), or if a live note has since taken the same title (rename one of them first, then retry).
search_notesSearch notes: hybrid (keyword + meaning) by default. Returns ranked excerpts, not whole notes. - Use type="text" for an exact identifier, filename, code symbol or quoted phrase; "hybrid" for questions and topics. - READ THE SECTION, NOT THE NOTE. A hit's `section` is the heading its excerpt came from — pass that string to get_note's `section` to get that part alone. If a long hit has no `section`, get_note with limit:1000 returns its `headings` outline; pick one and re-read with `section`. For prose without headings, a hit's `excerpt_offset` goes to get_note as `offset`. `other_sections` names more sections of the same note that match: read them too, since a note kept as a log may revise the shown entry in a later one. - A hit is a candidate, not an answer. `relevance` is relative to the best hit in this response, so the top result always reads 1.0 — an ordering, not a verdict; `best_score` is that hit's own raw similarity. `matched_by` says which arms found it: semantic_score alone means "about something similar", never that it confirms your question. Quote the excerpt or open the note — a score is never evidence. `exact:true` means the query occurs verbatim in that note; `text_tier` of "or" or "substring" means the strict words missed and a looser pass filled in — recall, not confirmation. - A long note such as a book comes back as one hit with one excerpt. To find more places in it, search again with its `note_id`: results are then places inside that note, best first. - Dates here filter, they do not rank. For "what changed lately" use list_notes, which sorts by recency; it is also how you browse by folder or tag, since a query is required here. - `has_more` with `next_offset` pages the results.
indexing_statusSemantic index progress: total/indexed/pending, complete=true when pending is 0. Pending notes are still found by text search; ones never embedded stay out of semantic results until the background pass reaches them. Also names the active embedding model and the configured similarity cutoff (`semantic_min_similarity`, null when there is none — the default, meaning nothing is refused for being too dissimilar). Cosines are not comparable between models, which is why the model is named rather than left to be guessed from a score.
list_tagsTags in use with the number of notes carrying each, most-used first. The default limit cuts off the one-off tail — a tag used once is not one worth reusing — so raise it to see those.
list_foldersList folders with the full path already resolved — no need to walk parent_id yourself. Pass a folder's own id as parent_id to create_folder/update_folder to nest under it. Sorted by path, so a page is a contiguous slice of the tree read top to bottom; the reply is `{folders, has_more, next_offset?}`.
Show all 18 toolsShow fewer tools
create_folderCreate a new folder. Optionally nested under a parent.
update_folderRename a folder and/or move it under a different parent (set parent_id to null for top level). Provide at least one of name/parent_id. The response includes the resolved `path` so a rename or move can be confirmed without a follow-up list_folders call.
delete_folderDelete a folder and its full subtree of child folders (cascade). Every note inside — including notes in nested subfolders — is soft-deleted into the trash along with it (see delete_note), recoverable via restore_note within the retention window. To preserve organization instead, move notes/subfolders out first.
get_backlinksNotes that link to this one via [[Title]] wikilinks, by id or title. Each comes back as id/title/folder_path plus a snippet around the link; include_content:true returns their full text instead, which is expensive when many notes link here — prefer get_note on the ids you actually want. offset and limit count notes, not characters.
get_neighborsWhat is around ONE note in the [[wikilink]] graph, out to `depth` hops: a flat list of titles, no node indices to decode and no whole-vault payload. For the shape of that neighbourhood — which of them link to each other — use get_graph with root_title instead. Traversal is undirected: a note linking HERE counts as much as one linked FROM here. `links_out`/`links_in` describe the direct relation and appear only at depth 1 — two hops out, "which way does the arrow point" has no answer. Each note appears once, at the shortest depth that reaches it. These are links people wrote, not similarity: a note on the same subject that nobody linked is not here, and an empty result is a fact about the writing rather than about the topic. Rows carry the title, which is what get_note, get_backlinks and this tool all take.
get_graphMany notes at once and the edges between them — the heavy graph tool, and the only one that reaches for the whole vault. For one note's surroundings use get_neighbors; for who links to it, get_backlinks. Nodes are `{t}` (t = title). Edges reference nodes BY POSITION in the `nodes` array: `edges[0] = [2, 5]` means nodes[2] links to nodes[5]. semantic_edges are undirected and come from embedding similarity rather than written links, with the cosine as a third number. `unresolved_links` are [[wikilink]] targets matching no note title — dangling, so they have no node index. Unscoped this reaches for the ENTIRE vault and stops at max_nodes: `truncated: true` means you hold a recency-ordered prefix, NOT the shape of the vault. Scope with folder_id or root_title+depth rather than raising the cap.
Configuration
DATABASE_URLSecretUse an existing Kybase Postgres instead of the embedded one (migrations are left to the app)
GOOGLE_API_KEYSecretGoogle API key, when EMBEDDING_PROVIDER=google. Sends note text to Google
OPENAI_API_KEYSecretOpenAI API key, when EMBEDDING_PROVIDER=openai. Sends note text to OpenAI
EMBEDDING_PROVIDEREmbedding provider for semantic search
KYBASE_DATA_DIRWhere the embedded database and instance secret live. Defaults to ~/.kybase
OLLAMA_MODELOllama embedding model
OLLAMA_URLOllama endpoint for local embeddings. Without any provider, full-text search still works
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubkybase-mcp
Persistent memory for AI agents, as a single command:
npx kybase-mcp
No Docker, no database to install, no server to run. The first start
creates a local knowledge base under ~/.kybase and speaks MCP over
stdio. Your notes are plain Markdown in Postgres — running on your
machine, leaving it only if you choose a cloud embedding provider.
This is the same MCP server the full Kybase app exposes over HTTP. Use this package when you want memory for a local agent; use the full app when you also want the web UI, the knowledge graph view, sharing, and access for several agents at once.
Connect an agent
Claude Code — .mcp.json in your project, or claude mcp add:
{
"mcpServers": {
"kybase": {
"command": "npx",
"args": ["-y", "kybase-mcp"]
}
}
}
Claude Desktop — the same block in claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json,
Windows: %APPDATA%\Claude\claude_desktop_config.json).
Cursor — the same block in .cursor/mcp.json or ~/.cursor/mcp.json.
Several clients on one machine can use it at once: the first process to start owns the database, and the others connect to that process.
Restart the client and ask it to remember something. It gets 18 tools for reading, searching, writing, and linking notes.
Claude Desktop, one click — download kybase-mcp-<version>.mcpb from
Releases and open it; the
data folder and embedding provider are set in the extension's settings.
The server is listed in the official MCP Registry as
io.github.Kyrzin/kybase.
Search
Full-text search works immediately, in English and Russian, accent- and case-insensitive.
Semantic search — finding a note by meaning when it shares no words with your question — needs an embedding provider. The local option is Ollama:
ollama pull embeddinggemma
OLLAMA_URL=http://localhost:11434 npx kybase-mcp
Existing notes are embedded in the background as soon as a provider is
available; indexing_status reports progress. Without one, nothing
breaks — semantic search simply stays idle.
Reading your notes
The embedded database is not a folder of .md files, so this writes the
whole vault out as one:
kybase-mcp export vault.zip
Plain Markdown with frontmatter, folders as directories, [[wikilinks]]
intact — open it in any editor. It is also exactly the archive the full
Kybase app accepts under Settings → Import .zip, so starting here and
moving to the web UI later costs one command in each direction.
Configuration
Every variable is optional.
| Variable | Default | What it does |
|---|---|---|
KYBASE_DATA_DIR |
~/.kybase |
Where the database and instance secret live. |
DATABASE_URL |
(unset) | Point at an existing Kybase Postgres instead of the embedded one. In this mode the package does not run migrations — the app that owns the schema does. |
EMBEDDING_PROVIDER |
ollama |
ollama, google, or openai. |
OLLAMA_URL |
(unset) | e.g. http://localhost:11434. Enables semantic search. |
OLLAMA_MODEL |
embeddinggemma |
Multilingual by default; nomic-embed-text is smaller and English-leaning. |
GOOGLE_API_KEY / OPENAI_API_KEY |
(unset) | Cloud embedding providers. Picking one sends your note text to that provider. |
Build from source
The package bundles code from the main repository, so build it from a checkout rather than from this directory alone:
git clone https://github.com/Kyrzin/kybase.git
cd kybase/packages/kybase-mcp
npm install # also builds, via the prepare script
npm install -g . # puts `kybase-mcp` on your PATH
Your data
Everything is under KYBASE_DATA_DIR:
pgdata/— the database itself (Postgres compiled to WebAssembly, with pgvector). Copy the directory to back it up.secret— generated on first run,0600. It encrypts any embedding provider API keys you store. Keep it with the data.run/— the unix socket the database listens on, in a0700directory. It has no password, so file permissions are the access control. Windows cannot listen on a socket path, so there the database binds an unused loopback port instead — reachable by other processes running as you, and never from another machine.KYBASE_EMBEDDED_TCP=1forces that mode on Unix too, for a data directory on a filesystem that cannot host a socket.
Expect the process to hold a few hundred MB of memory while it runs: the
embedded database is a full Postgres, and it lives inside it. Pointing
DATABASE_URL at a Postgres you already run avoids that entirely.
Note content is plain Markdown and every note is readable through the MCP
tools, so an agent can always read the whole vault back out, and
kybase-mcp export writes it out as files — see
Reading your notes.
License
Kybase MCP questions
How do I add Kybase MCP to Claude Code?
Run claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'GOOGLE_API_KEY=<YOUR_GOOGLE_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' kybase -- npx -y kybase-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Kybase MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Kybase MCP provide?
It exposes 18 tools, including list_notes, get_note, create_note, update_note, append_to_note.
How do I enable semantic search?
Semantic search requires an embedding provider like Ollama, Google, or OpenAI. For a local setup, you can use Ollama by setting the OLLAMA_URL environment variable.
Does this require installing a separate database?
No, it uses an embedded Postgres database that runs locally on your machine without requiring Docker or a separate installation.