SeekLink

English · 中文

SeekLink 是一个用于 Markdown 知识库的本地语义搜索 CLI 工具，同时也是一个可选的只读 MCP stdio 服务器。它会对 .md 文件文件夹进行索引，通过关键词+向量混合检索进行搜索，并返回人类和智能体可以通过简单 shell 命令读取的行锚点结果。

它专为个人知识库、兼容 Obsidian 的库、中英双语笔记以及本地智能体工作流而构建。Claude Code、Cursor 和 VS Code 等 MCP 客户端可以通过 seeklink[mcp] 调用相同的只读搜索/获取/状态/诊断接口。它也是 Markdown 维基模式（如 Andrej Karpathy 的 llm-wiki）的实用搜索层：智能体可以搜索现有页面，读取精确的行窗口，然后在不将知识库发送到托管服务的情况下更新维基。

一切都在本地运行。无需 API 密钥。无需云搜索服务。无需 Obsidian 插件。

安装

uv tool install seeklink
# or
pip install seeklink

对于 Apple Silicon 的重排序支持，请安装可选的 MLX 扩展：

uv tool install "seeklink[mlx]"
# or
pip install "seeklink[mlx]"

对于 Claude Code、Cursor 或 VS Code 等模型上下文协议 (MCP) 客户端，请安装可选的 MCP 扩展：

uv tool install "seeklink[mcp]"
# or
pip install "seeklink[mcp]"

SeekLink 要求 Python 的 sqlite3 模块链接到 SQLite 3.45 或更高版本，并启用 FTS5。seeklink status --vault PATH 会检查此项，如果运行时 SQLite 版本过旧，则会打印清晰的错误信息。

快速入门

# 1. Build the index first.
seeklink index --vault /path/to/vault

# 2. Search it.
seeklink search "machine learning" --vault /path/to/vault

如果设置了默认知识库，日常使用会更简单：

export SEEKLINK_VAULT=/path/to/vault
seeklink index
seeklink search "agent memory systems"
seeklink get notes/agent-memory-patterns.md:1 -C 20

当未传递 --vault 时，seeklink search 和单文件 seeklink index path/to/file.md 会使用驻留守护进程。守护进程将嵌入模型和可选的重排序模型保持在内存中；在 macOS 上，这表现为一个本地的 Python 进程。它仅限本地使用，使用 Unix 套接字，不会打开网络端口或调用云服务。默认情况下，它在 15 分钟不活动后退出。全库 seeklink index 在进程内运行，因此进度会显示在 stderr 上，最终的 Done: 摘要会显示在 stdout 上。seeklink status 和 seeklink get 始终保持冷启动：status 仅读取 SQLite 元数据，get 直接从磁盘读取文件。当脚本需要一次性冷启动路径时，请使用 --no-daemon、SEEKLINK_NO_DAEMON=1 或显式的 --vault PATH。

MCP 用户遵循相同的第一步：在注册 MCP 服务器之前，使用 seeklink index --vault PATH 构建索引。

输出

文本搜索输出是稳定的：

  SCORE  PATH[:LINE]  TITLE
           <content preview, one line, up to 120 chars>

• PATH 是相对于知识库根目录的路径。

• LINE 是 1-索引的，指向当前文件中最匹配的块。

• 退出代码：0 表示成功（包括无结果）；1 表示 SeekLink 检测到的运行时知识库/配置/文件错误；2 表示参数解析导致的命令行使用错误。

• 分数对于单次查询内的排序很有用。请勿比较启用重排序和禁用重排序运行之间的分数。

当智能体需要结构化输出时，请使用 JSON：

seeklink search "agent memory systems" --vault PATH --json
seeklink status --vault PATH --json
seeklink doctor --vault PATH --json
seeklink daemon status --json

常用命令

搜索

seeklink search "query" --vault PATH [options]

选项：

--top-k N          Number of results. Default: 10.
--json             Emit one machine-readable JSON object.
--tags TAG [TAG]   Filter by tags. AND semantics.
--folder PREFIX    Filter by vault-relative folder prefix.
--rerank-k N|auto  Rerank candidate budget. Default: auto.
--no-rerank        Skip cross-encoder reranking for this query.
--no-daemon        Force an in-process search instead of using the daemon.
--title-weight F   Override title/alias/heading channel weight. Default: 1.5.

获取

在不使用数据库或守护进程的情况下读取精确的文件窗口：

seeklink get notes/spaced-repetition.md
seeklink get notes/spaced-repetition.md:12
seeklink get notes/spaced-repetition.md:12 -l 40
seeklink get notes/spaced-repetition.md:12 -C 20

-l/--lines 打印从 LINE 开始的行。-C/--context 以 grep 风格打印 LINE 前后的行。路径转义（如 ../..）将被拒绝。

状态

seeklink status --vault PATH
seeklink status --vault PATH --json

状态报告索引计数、模型名称、索引配置兼容性、SQLite WAL 状态和新鲜度警告。它不会加载嵌入或重排序模型。

诊断

seeklink doctor --vault PATH
seeklink doctor --vault PATH --json

诊断检查 Python、SQLite、本地数据库、索引兼容性、守护进程状态以及可选的 MLX 可用性。它不会下载或加载模型，但如果缺失，可能会初始化本地 SeekLink 数据库/架构。

MCP

可选的模型上下文协议 (MCP) 适配器允许智能体客户端直接发现并调用 SeekLink 的只读工具。CLI 继续独立工作；MCP 是同一检索路径的另一个接口，而不是替代品。

seeklink mcp --vault PATH

使用 seeklink[mcp] 安装它。首先使用 CLI 构建索引：seeklink index --vault PATH。MCP 适配器是只读的，并公开四个工具：search、get、status 和 doctor。它不公开 index、写入笔记、使用 HTTP/OAuth 或通过 Unix 套接字守护进程路由。每个知识库运行一个 MCP 服务器。search 通过路径和行锚点保持其文本摘要紧凑；结果预览保留在结构化内容中，供需要的智能体使用。当现有的 .seeklink/seeklink.db 需要时，status 和 doctor 可能会初始化或迁移本地 SeekLink 架构，但它们不会索引或修改 Markdown 笔记。如果您的 MCP 客户端没有继承您的 shell PATH，请在下面的示例中使用 which seeklink 得到的绝对路径。

Claude Code:

claude mcp add --transport stdio --scope project seeklink \
  -- seeklink mcp --vault /ABS/PATH/TO/VAULT

Cursor .cursor/mcp.json:

{
  "mcpServers": {
    "seeklink": {
      "type": "stdio",
      "command": "seeklink",
      "args": ["mcp", "--vault", "/ABS/PATH/TO/VAULT"]
    }
  }
}

VS Code .vscode/mcp.json:

{
  "servers": {
    "seeklink": {
      "type": "stdio",
      "command": "seeklink",
      "args": ["mcp", "--vault", "/ABS/PATH/TO/VAULT"]
    }
  }
}

索引

seeklink index --vault PATH
seeklink index path/to/file.md --vault PATH

全库索引会根据内容哈希跳过未更改的文件，除非存储的索引是使用不同的嵌入器、向量维度或分块配置构建的，在这种情况下，SeekLink 会重建派生的索引内容。单文件索引仅在现有索引配置兼容时更新一个 Markdown 文件。

守护进程

seeklink daemon status
seeklink daemon stop
seeklink daemon restart
seeklink daemon pid
seeklink daemon run --vault PATH

通常不需要手动启动守护进程。search 和单文件 index 会在适当的时候自动生成并自动重启它，然后在 SEEKLINK_DAEMON_IDLE_TIMEOUT 秒不活动后退出。默认值为 900 秒（15 分钟）；将其设置为 0、off、false 或 no 可保持守护进程处于活跃状态，直到停止。

全库 index 仍然在进程内运行以输出进度。将 --vault 传递给 search 或单文件 index 会强制执行一次性冷启动路径，因为守护进程在启动时绑定到一个知识库。--no-daemon 和 SEEKLINK_NO_DAEMON=1 也会强制执行相同的冷启动路径。使用 seeklink daemon status 检查活跃进程，使用 seeklink daemon stop 立即释放其内存。

搜索原理

SeekLink 通过倒数排名融合 (Reciprocal Rank Fusion) 融合了四个通道：

默认嵌入器是通过 fastembed 使用的 jinaai/jina-embeddings-v2-base-zh。当本地 Python/SQLite 构建可以安全注册时，CJK 全文搜索使用 jieba FTS5 分词器；否则 SeekLink 会回退到 SQLite 内置的三元组分词器，而不是崩溃。

默认向量维度为 768。高级自定义嵌入器实验可以设置 SEEKLINK_EMBEDDING_DIM，但它必须与嵌入器输出匹配，并且需要完整的 seeklink index 重建。

在 Apple Silicon 上，当安装了 seeklink[mlx] 时，SeekLink 可以使用 mlx-community/Qwen3-Reranker-0.6B-mxfp8 对候选结果进行重排序。重排序是本地且可选的；如果 MLX 不可用，SeekLink 会回退到第一阶段的混合 RRF 排名。对单次查询使用 --no-rerank 或设置 SEEKLINK_RERANKER_MODEL="" 可全局禁用它。

Frontmatter

Markdown frontmatter 是可选的。当存在时，SeekLink 会将其用于标签和别名：

---
tags: [ai, memory]
aliases: [LLM memory, agent memory]
---

• tags 支持过滤搜索：seeklink search "memory" --tags ai

• aliases 被索引以供搜索，并在解析维基链接时使用

存储

SeekLink 在知识库内写入一个 SQLite 数据库：

/path/to/vault/.seeklink/seeklink.db

该数据库包含源元数据、块、FTS5 表、sqlite-vec 向量和维基链接图。删除 .seeklink/ 并运行 seeklink index 即可重建。

支持情况

不适用场景

• 托管或同步的多用户搜索。

• 未经转换的非 Markdown 源。

• GUI 或 Obsidian 插件。

• 对数百万条笔记进行亚毫秒级搜索。

• 云嵌入或重排序 API。

智能体说明

智能体可以通过普通的子进程调用使用 SeekLink：

seeklink status --vault PATH
seeklink index --vault PATH
seeklink search "query" --vault PATH --json
seeklink get PATH:LINE -C 20 --vault PATH

MCP 客户端可以使用可选的只读适配器：

seeklink mcp --vault PATH

要让智能体为 Markdown 知识库选择 SeekLink，请将其添加到项目的 AGENTS.md、CLAUDE.md 或编辑器规则中：

When you need to search or inspect this Markdown vault, use SeekLink for
semantic retrieval:

1. Run `seeklink status --vault PATH --json`.
2. If no index exists or files changed, run `seeklink index --vault PATH`.
3. Run `seeklink search "QUERY" --vault PATH --json`.
4. Read exact context with `seeklink get PATH:LINE -C 20 --vault PATH`.

If SeekLink is registered as an MCP server in this client, prefer the
`search`, `get`, `status`, and `doctor` MCP tools over shelling out to the CLI.

Prefer SeekLink for conceptual, cross-language, tag/folder-filtered, or
Obsidian-style note searches. Use rg for exact literal searches.

对于热循环，守护进程通过 ~/.rhizome/seeklink.sock 上的 Unix 套接字公开长度前缀的 JSON 协议。除非特别需要套接字级延迟，否则大多数智能体应优先使用 CLI JSON 接口。

请参阅 llms.txt 获取紧凑的智能体契约。

评估

搜索质量测试位于 tests/blind/；该方法记录在 docs/blind-test.md 中。发布声明应由捆绑的固定查询或清晰标记的私有知识库测量结果支持。

贡献

git clone https://github.com/simonsysun/seeklink
cd seeklink
uv sync --dev
uv run python -m pytest tests/ -q

保持运行时依赖项精简，保持公共文档面向用户，并为用户可见的更改添加 CHANGELOG.md 条目。

许可证

MIT