SeekLink

SeekLink

English · 中文

状态：暂停维护。 SeekLink 已不再积极维护。对于同类、仍在积极开发的本地 Markdown 搜索引擎——支持本地混合关键词 + 向量搜索、按行锚定结果、CLI + MCP 和多语言——我们推荐 qmd。

SeekLink 是一款本地语义搜索 CLI，也可选用只读 MCP stdio 服务，适用于 Markdown 知识库。它会为 .md 文件所在文件夹建立索引，使用混合关键词 + 向量检索，并返回按行锚定的结果，方便人类和 Agent 使用简单的 shell 命令读取。

它适用于个人知识库、兼容 Obsidian 的知识库、英中双语笔记和本地 Agent 工作流。Claude Code、Cursor 和 VS Code 等 MCP 客户端可通过 seeklink[mcp] 调用相同的只读搜索/获取/状态/诊断功能。它也适用于 Andrej Karpathy 的 llm-wiki 等 Markdown wiki 模式：Agent 可以搜索现有页面、读取精确的行范围，然后更新 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 等 Model Context Protocol（MCP）客户端，请安装可选的 MCP 扩展：

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

SeekLink 要求 Python 的 sqlite3 模块链接到启用了 FTS5 的 SQLite 3.45 或更高版本。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；SeekLink 检测到运行时知识库/配置/文件错误时为 1；参数解析导致的命令行用法错误时为 2。
• 分数适合在单次查询内排序。请勿比较启用和未启用重排器时的分数。

Agent 需要结构化输出时，请使用 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 状态和新鲜度警告。它不会加载嵌入模型或重排模型。

Doctor

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

Doctor 会检查 Python、SQLite、本地数据库、索引兼容性、守护进程状态，以及 MLX 是否可用（可选）。它不会下载或加载模型，但在本地 SeekLink 数据库/架构不存在时，可能会进行初始化。

MCP

可选的 Model Context Protocol (MCP) 适配器让 Agent 客户端能够直接发现并调用 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 会保持文本摘要简洁，并附带路径和行锚点；需要预览结果的 Agent 可在结构化内容中查看。对于已有的 .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 时仍会在进程内执行，以便显示进度。对 search 或单文件 index 传入 --vault，会强制使用一次性冷启动路径，因为守护进程在启动时会绑定到一个知识库。--no-daemon 和 SEEKLINK_NO_DAEMON=1 也会强制使用相同的冷启动路径。使用 seeklink daemon status 检查常驻进程，使用 seeklink daemon stop 立即释放其内存。

搜索原理

SeekLink 使用 Reciprocal Rank Fusion 融合以下四个通道：

通道	用途
BM25 / FTS5	精确词语、代码术语、缩写、CJK 词法匹配
向量搜索	不同措辞之间的语义匹配
标题 / 别名 / 标题层级	精确查找笔记和章节
Wikilink 入度	根据现有 [[links]] 得出的轻量图质量先验

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

默认向量维度为 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 会被编入搜索索引，并在解析 wikilink 时使用

存储

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

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

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

支持情况

区域	状态
Python	3.11、3.12、3.13、3.14
SQLite	与 SQLite 3.45+ 链接且启用 FTS5 的 Python sqlite3
OS	macOS 和 Linux
Windows	不作为一等支持平台
文件格式	Markdown .md
知识库风格	普通文件夹或兼容 Obsidian 的知识库
CJK	通过 jieba 使用原生路径，静态 SQLite 构建时回退到 trigram
重排器	Apple Silicon 上可选的 seeklink[mlx] 附加项；其他平台禁用
守护进程	每台机器仅支持一个知识库
MCP	可选的 seeklink[mcp] stdio 适配器，每个知识库一个服务

不适用场景

• 托管式或同步式的多用户搜索。
• 未经转换的非 Markdown 来源。
• GUI 或 Obsidian 插件。
• 对数百万条笔记进行亚毫秒级搜索。
• 云端嵌入或重排 API。

Agent 说明

Agent 可以通过普通子进程调用使用 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

若要让 Agent 为 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 协议。除非确实需要套接字级延迟，大多数 Agent 应优先使用 CLI JSON 接口。

精简版 Agent 约定见 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