Seek Link

SeekLink

英语 · 中文

   

SeekLink是一个本地语义搜索CLI和可选的只读MCP stdio服务器 用于Markdown Vault。它为以下文件夹建立索引 .md 文件，混合搜索 关键字+向量检索，并返回人类和 代理可以使用简单的shell命令进行读取。

它是为个人知识库、黑曜石兼容库、双语库而构建的 中英文笔记和本地代理工作流程。MCP客户，如Claude Code、Cursor和VS Code可以调用相同的只读搜索/获取/状态/医生 表面通过 seeklink[mcp]。它也是Markdown的一个有用的搜索层 维基模式，如Andrej Karpathy的 llm维基: 代理可以搜索现有页面，读取精确的行窗口，然后更新 wiki，而无需将保管库发送到托管服务。

一切都在本地运行。没有API密钥。没有云搜索服务。无黑曜石插件 必修的。

安装

uv tool install seeklink
# or
pip install seeklink

要获得Apple Silicon重新分级支持，请安装可选的MLX extra：

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

对于模型上下文协议（MCP）客户端，如Claude Code、Cursor或VS 代码，安装可选的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

seeklink search 单个文件 seeklink index path/to/file.md 使用一个 常驻守护进程 --vault 未通过。守护进程保留嵌入器和 可选的内存中热重启器；在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用户遵循相同的第一步：使用 seeklink index --vault PATH 在注册MCP服务器之前。

输出

文本搜索输出稳定：

  SCORE  PATH[:LINE]  TITLE
           

• PATH 相对于vault根。
• LINE 是1-索引的，指向当前文件中最匹配的块。
• 退出代码为 0 为了成功，包括没有结果； 1 运行时

SeekLink检测到vault/config/file错误；和 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 之前打印线条 之后 LINE，grep风格。路径逃逸，例如 ../.. 被拒绝。

状态

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）适配器允许代理客户端发现 并直接调用SeekLink的只读工具。CLI继续工作 独立地；MCP是同一检索路径的另一个表面，而不是 替换。

seeklink mcp --vault PATH

用以下方式安装 seeklink[mcp].首先使用CLI构建索引： seeklink index --vault PATHMCP适配器是只读的，暴露了四个 工具： search, get, status，以及 doctor。它不会暴露 index, 写笔记、使用HTTP/OAuth或通过Unix套接字守护进程路由。跑一个 每个保险库的MCP服务器。 search 使其文本摘要与路径和 线锚；结果预览保留在结构化内容中，供需要的代理使用 他们。 status 和 doctor 可以初始化或迁移本地SeekLink架构 当一个现有 .seeklink/seeklink.db 需要它，但他们不索引或 修改Markdown注释。如果您的MCP客户端没有继承您的shell PATH, 使用来自的绝对路径 which seeklink 在下面的例子中。

克劳德代码：

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

光标 .cursor/mcp.json:

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

VS代码 .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

完整vault索引通过内容哈希跳过未更改的文件，除非存储了 索引是用不同的嵌入器、向量维度或分块器构建的 配置，在这种情况下，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通过往复式秩融合融合了四个信道：

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

默认矢量维度为768。高级定制嵌入器实验可以 集 SEEKLINK_EMBEDDING_DIM，但它必须与嵌入器输出匹配，并要求 满满的 seeklink index 重建。

在Apple Silicon上，SeekLink可以对候选人进行重新排名 mlx-community/Qwen3-Reranker-0.6B-mxfp8 安装时 seeklink[mlx]. 重新排名是本地和可选的；如果MLX不可用，SeekLink将回退到 第一阶段混合RRF排名。使用 --no-rerank 对于一个查询或集合 SEEKLINK_RERANKER_MODEL="" 在全球范围内禁用它。

前言

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

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

• tags 支持过滤搜索： seeklink search "memory" --tags ai
• aliases 被编入索引以供搜索，并在解析维基链接时使用

存储

SeekLink在vault中写入一个SQLite数据库：

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

数据库包含源元数据、块、FTS5表、sqlite-vec向量、， 以及维基链接图。删除 .seeklink/ 然后跑 seeklink index 重建。

支持

不是为了

• 托管或同步多用户搜索。
• 未经转换的非Markdown源代码。
• GUI或黑曜石插件。
• 对数百万张纸币进行亚毫秒级搜索。
• 云嵌入或重新分级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 vault选择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.

对于热循环，守护进程在Unix上公开了一个长度前缀的JSON协议 插座 ~/.rhizome/seeklink.sock。大多数代理应该更喜欢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 用户可见更改的条目。

许可证

麻省理工学院