Kybase

Name: Kybase
Author: Kyrzin

本地服务

kyrzin.github.io记忆与知识66 天前更新

代码仓库访问官网

关于 Kybase

Kybase 是面向 Agent 的本地 MCP 记忆服务，将可编辑的 Markdown 笔记存入嵌入式 Postgres。默认提供全文搜索，配置嵌入提供商后可进行语义搜索。

主要功能

01本地嵌入式 Postgres 存储
02支持 wikilinks 的 Markdown 笔记
03全文与语义搜索
04提供 18 个笔记操作工具
05将笔记库导出为 ZIP

适用场景

01为本地 Agent 持久保存记忆
02按文本或含义搜索笔记
03导出笔记库以便编辑

MCP 相关

通过 stdio 向 MCP 客户端提供 18 个用于读取、搜索、编写和链接笔记的工具。同一台机器上的多个客户端可共用运行中的数据库进程。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "kyrzin-kybase": {
      "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>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "DATABASE_URL": "<DATABASE_URL>"
      }
    }
  }
}

启动命令npx -y kybase-mcp

需要配置的环境变量

KYBASE_DATA_DIRWhere the embedded database and instance secret live. Defaults to ~/.kybase

EMBEDDING_PROVIDEREmbedding provider for semantic search

OLLAMA_URLOllama endpoint for local embeddings. Without any provider, full-text search still works

OLLAMA_MODELOllama embedding model

GOOGLE_API_KEY密钥Google API key, when EMBEDDING_PROVIDER=google. Sends note text to Google

OPENAI_API_KEY密钥OpenAI API key, when EMBEDDING_PROVIDER=openai. Sends note text to OpenAI

DATABASE_URL密钥Use an existing Kybase Postgres instead of the embedded one (migrations are left to the app)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmkybase-mcp0.2.3stdio

工具

收录的工具列表 · 更新于 6 天前

参数	类型	必填	说明
tag	string	否	按标签筛选
sort	enum	否	用于排序的日期created \| updated
limit	integer	否	每页最多返回的笔记数。软删除模式下同样适用
offset	integer	否	跳过的笔记数——传入上一页返回的 next_offset
trashed	boolean	否	列出软删除的笔记，而非有效笔记
folder_id	string	否	按文件夹 UUID 筛选——仅筛选该文件夹本身，不包括其子文件夹
folder_path	string	否	按路径（例如 "Projects/Kybase"）而非 UUID 进行相同筛选——仅筛选该文件夹本身，不包括其子文件夹
created_after	string	否	ISO 时间戳——仅包含在此时间或之后创建的笔记
updated_after	string	否	ISO 时间戳——仅包含在此时间或之后自身内容实际发生更改的笔记
created_before	string	否	ISO 时间戳——仅包含在此时间或之前创建的笔记
updated_before	string	否	ISO 时间戳——仅包含在此时间或之前自身内容实际发生更改的笔记

详细介绍

kybase-mcp

为 AI Agent 提供持久记忆，只需一条命令：

npx kybase-mcp

无需 Docker，无需安装数据库，也无需运行服务。首次启动时会在 ~/.kybase 下创建本地知识库，并通过标准输入输出（stdio）使用 MCP。你的笔记以纯 Markdown 格式存储在 Postgres 中——数据库运行在你的机器上，只有在你选择云端嵌入服务提供商时，笔记才会离开本机。

这与完整的 Kybase 应用通过 HTTP 提供的 MCP 服务相同。需要为本地 Agent 提供记忆时，请使用此软件包；如果还需要 Web UI、知识图谱视图、共享功能，以及供多个 Agent 同时访问，请使用完整应用。

连接 Agent

Claude Code — 在项目中使用 .mcp.json，或运行 claude mcp add：

{
  "mcpServers": {
    "kybase": {
      "command": "npx",
      "args": ["-y", "kybase-mcp"]
    }
  }
}

Claude Desktop — 在 claude_desktop_config.json 中使用相同的配置块（macOS：~/Library/Application Support/Claude/claude_desktop_config.json， Windows：%APPDATA%\Claude\claude_desktop_config.json）。

Cursor — 在 .cursor/mcp.json 或 ~/.cursor/mcp.json 中使用相同的配置块。

同一台机器上的多个客户端可以同时使用它：第一个启动的进程负责运行数据库，其他进程则连接到该进程。

重启客户端，然后让它记住一些内容。它会获得 18 个用于读取、搜索、编写和关联笔记的工具。

Claude Desktop，一键安装 — 从 Releases 下载 kybase-mcp-<version>.mcpb 并打开；数据文件夹和嵌入服务提供商可在扩展程序的设置中配置。

此服务已列入官方 MCP Registry，名称为 io.github.Kyrzin/kybase。

搜索

全文搜索开箱即用，支持英语和俄语，并且不区分重音符号和大小写。

语义搜索——即使笔记与问题没有任何共同词汇，也能按含义找到笔记——需要嵌入服务提供商。本地选项是 Ollama：

ollama pull embeddinggemma
OLLAMA_URL=http://localhost:11434 npx kybase-mcp

有了服务提供商后，现有笔记会立即在后台进行嵌入；indexing_status 会报告进度。没有服务提供商也不会影响其他功能——语义搜索只会保持闲置。

阅读你的笔记

嵌入式数据库不是由 .md 文件组成的文件夹，因此可以用以下命令将整个知识库导出为一个文件：

kybase-mcp export vault.zip

纯 Markdown 格式，包含 frontmatter，文件夹会作为目录保留，[[wikilinks]] 也会完整保留——可以用任何编辑器打开。它也是完整 Kybase 应用在 Settings → Import .zip 中可接受的归档格式，因此先从这里开始、之后再迁移到 Web UI，只需分别运行一条命令。

配置

所有变量均为可选项。

变量	默认值	作用
`KYBASE_DATA_DIR`	`~/.kybase`	数据库和实例密钥的存放位置。
`DATABASE_URL`	(未设置)	指向现有的 Kybase Postgres，而非嵌入式数据库。此模式下软件包不会运行迁移——由负责管理架构的应用执行迁移。
`EMBEDDING_PROVIDER`	`ollama`	可选 `ollama`、`google` 或 `openai`。
`OLLAMA_URL`	(未设置)	例如 `http://localhost:11434`。启用语义搜索。
`OLLAMA_MODEL`	`embeddinggemma`	默认支持多种语言；`nomic-embed-text` 体积更小，偏向英语。
`GOOGLE_API_KEY` / `OPENAI_API_KEY`	(未设置)	云端嵌入服务提供商。选择其中之一会将笔记文本发送给相应的服务提供商。

从源代码构建

此软件包包含主仓库中的代码，因此应从克隆的仓库构建，而不是只在此目录中构建：

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

您的数据

所有内容都位于 KYBASE_DATA_DIR 下：

pgdata/ — 数据库本身（编译为 WebAssembly 的 Postgres，带有 pgvector）。复制此目录即可备份。
secret — 首次运行时生成，权限为 0600。它用于加密您存储的嵌入服务提供商 API 密钥。请将它与数据一并保留。
run/ — 数据库监听的 Unix 套接字，位于权限为 0700 的目录中。它没有密码，因此访问控制由文件权限负责。Windows 无法监听套接字路径，因此数据库会改为绑定一个未使用的 loopback 端口 — 您运行的其他进程可以访问，但无法从其他机器访问。 KYBASE_EMBEDDED_TCP=1 也会在 Unix 上强制使用此模式，适用于无法承载套接字的文件系统上的数据目录。

运行期间，进程预计会占用几百 MB 内存：嵌入式数据库是一个完整的 Postgres，并且运行在进程内部。将 DATABASE_URL 指向您已运行的 Postgres，即可完全避免此情况。

笔记内容为纯 Markdown，且每条笔记都可通过 MCP 工具读取，因此 Agent 始终可以读取整个知识库； kybase-mcp export 会将其写成文件 — 请参阅读取您的笔记。