Kybase — Claude Code MCP server for agent memory
A local Markdown note base your agent reaches over MCP: it reads, searches and links notes across sessions.
claude mcp add --env KYBASE_DATA_DIR=<KYBASE_DATA_DIR> --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --env OLLAMA_URL=<OLLAMA_URL> --env OLLAMA_MODEL=<OLLAMA_MODEL> --env GOOGLE_API_KEY=<GOOGLE_API_KEY> --transport stdio kybase-mcp -- npx -y kybase-mcpWhat Kybase does
Kybase starts with npx kybase-mcp. No Docker, no separate database to set up. On the first run it creates a knowledge base in ~/.kybase and talks to the client over stdio. Notes stay plain Markdown inside Postgres, compiled to WebAssembly and running on your machine.
The agent gets 18 tools covering reading, searching, writing and linking. Full-text search is available right away in English and Russian, ignoring case and accents. Semantic search, which finds a note that shares no words with the question, needs an embedding provider. Ollama is the local choice: run ollama pull embeddinggemma, then OLLAMA_URL=http://localhost:11434 npx kybase-mcp. Nothing breaks without a provider — semantic search just sits idle, and indexing_status shows how indexing is going.
The embedded database is not a directory of .md files, so kybase-mcp export vault.zip writes the whole vault out as one. You get Markdown with frontmatter, folders as directories, [[wikilinks]] preserved. The same archive is what the full Kybase app takes under “Settings → Import .zip”. While the process runs it holds a few hundred MB of memory, since a full Postgres lives inside it. Pointing DATABASE_URL at a Postgres you already run avoids that, but then migrations belong to the app that owns the schema, not to this package.
What it helps with
- keep project context alive between agent sessions
- find a note by meaning when you forget the exact words
- export the whole note base as editable Markdown files
- link related notes with
[[wikilinks]] - keep agent memory local instead of in a cloud service
Example prompts for the agent
- Remember that deploys go through staging and save it as a note.
- Search the base for everything I wrote about Postgres migrations.
- Link this note to the one about the service architecture.
How to install Kybase
Platform CLI
claude mcp add --env KYBASE_DATA_DIR=<KYBASE_DATA_DIR> --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --env OLLAMA_URL=<OLLAMA_URL> --env OLLAMA_MODEL=<OLLAMA_MODEL> --env GOOGLE_API_KEY=<GOOGLE_API_KEY> --transport stdio kybase-mcp -- npx -y kybase-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add kybase-mcp --env KYBASE_DATA_DIR=<KYBASE_DATA_DIR> --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --env OLLAMA_URL=<OLLAMA_URL> --env OLLAMA_MODEL=<OLLAMA_MODEL> --env GOOGLE_API_KEY=<GOOGLE_API_KEY> -- npx -y kybase-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"kybase-mcp": {
"command": "npx",
"args": [
"-y",
"kybase-mcp"
],
"env": {
"KYBASE_DATA_DIR": "<KYBASE_DATA_DIR>",
"EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
"OLLAMA_URL": "<OLLAMA_URL>",
"OLLAMA_MODEL": "<OLLAMA_MODEL>",
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"kybase-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"kybase-mcp"
],
"env": {
"KYBASE_DATA_DIR": "<KYBASE_DATA_DIR>",
"EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
"OLLAMA_URL": "<OLLAMA_URL>",
"OLLAMA_MODEL": "<OLLAMA_MODEL>",
"GOOGLE_API_KEY": "<GOOGLE_API_KEY>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e KYBASE_DATA_DIR=<KYBASE_DATA_DIR> -e EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> -e OLLAMA_URL=<OLLAMA_URL> -e OLLAMA_MODEL=<OLLAMA_MODEL> -e GOOGLE_API_KEY=<GOOGLE_API_KEY> kybase-mcp npx -y kybase-mcpReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Kybase
How do I install Kybase in Claude Code?
Add the server with `claude mcp add kybase -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e DATABASE_URL=<DATABASE_URL> -- npx -y kybase-mcp`, then restart the client.
What does Kybase do?
It gives an agent persistent memory as a Markdown note base with full-text and semantic search, exposed through MCP tools.
Do I need a cloud embedding provider?
No. Full-text search works without one, and local Ollama is enough for semantic search. Choosing google or openai sends your note text to that service.
