SeekLink

English · 中文

SeekLink is a local semantic search CLI and optional read-only MCP stdio server for Markdown vaults. It indexes a folder of .md files, searches with hybrid keyword + vector retrieval, and returns line-anchored results that humans and agents can read with simple shell commands.

It is built for personal knowledge bases, Obsidian-compatible vaults, bilingual English/Chinese notes, and local agent workflows. MCP clients such as Claude Code, Cursor, and VS Code can call the same read-only search/get/status/doctor surface through seeklink[mcp]. It is also a useful search layer for Markdown wiki patterns such as Andrej Karpathy's llm-wiki: an agent can search existing pages, read precise line windows, then update the wiki without sending the vault to a hosted service.

Everything runs locally. No API key. No cloud search service. No Obsidian plugin required.

Install

uv tool install seeklink
# or
pip install seeklink

For Apple Silicon reranking support, install the optional MLX extra:

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

For Model Context Protocol (MCP) clients such as Claude Code, Cursor, or VS Code, install the optional MCP extra:

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

SeekLink requires Python's sqlite3 module to be linked against SQLite 3.45 or newer with FTS5 enabled. seeklink status --vault PATH checks this and prints a clear error if the runtime SQLite is too old.

Quick Start

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

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

Daily use is simpler if you set a default 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 and single-file seeklink index path/to/file.md use a resident daemon when --vault is not passed. The daemon keeps the embedder and optional reranker warm in memory; on macOS this appears as a local Python process. It is local-only, uses a Unix socket, and does not open a network port or call a cloud service. By default it exits after 15 minutes of inactivity. Full-vault seeklink index runs in-process so progress stays on stderr and the final Done: summary stays on stdout. seeklink status and seeklink get always stay cold-start: status only reads SQLite metadata, and get reads the file directly from disk. Use --no-daemon, SEEKLINK_NO_DAEMON=1, or an explicit --vault PATH when a script needs a one-shot cold-start path.

MCP users follow the same first step: build the index with seeklink index --vault PATH before registering the MCP server.

Output

Text search output is stable:

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

• PATH is relative to the vault root.
• LINE is 1-indexed and points to the best matching chunk in the current file.
• Exit code is 0 for success, including no results; 1 for runtime vault/config/file errors detected by SeekLink; and 2 for command-line usage errors from argument parsing.
• Scores are useful for sorting within one query. Do not compare scores across reranker-enabled and reranker-disabled runs.

Use JSON when an agent needs structured output:

seeklink search "agent memo

... [View full README on GitHub](https://github.com/simonsysun/seeklink#readme)