SeekLink

Inglés · 中文

SeekLink es una CLI de búsqueda semántica local y un servidor MCP stdio opcional de solo lectura para bóvedas Markdown. Indexa una carpeta de archivos .md, busca con recuperación híbrida de palabras clave + vectores y devuelve resultados anclados por línea que humanos y agentes pueden leer con comandos de shell simples.

Está diseñado para bases de conocimiento personales, bóvedas compatibles con Obsidian, notas bilingües inglés/chino y flujos de trabajo de agentes locales. Los clientes MCP como Claude Code, Cursor y VS Code pueden llamar a la misma superficie de búsqueda/obtención/estado/diagnóstico de solo lectura a través de seeklink[mcp]. También es una capa de búsqueda útil para patrones wiki de Markdown como llm-wiki de Andrej Karpathy: un agente puede buscar páginas existentes, leer ventanas de líneas precisas y luego actualizar la wiki sin enviar la bóveda a un servicio alojado.

Todo se ejecuta localmente. Sin clave API. Sin servicio de búsqueda en la nube. No requiere plugin de Obsidian.

Instalación

uv tool install seeklink
# or
pip install seeklink

Para soporte de reranking en Apple Silicon, instala el extra opcional MLX:

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

Para clientes del Protocolo de Contexto de Modelo (MCP) como Claude Code, Cursor o VS Code, instala el extra opcional MCP:

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

SeekLink requiere que el módulo sqlite3 de Python esté vinculado contra SQLite 3.45 o posterior con FTS5 habilitado. seeklink status --vault PATH verifica esto e imprime un error claro si el SQLite en tiempo de ejecución es demasiado antiguo.

Inicio rápido

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

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

El uso diario es más sencillo si estableces una bóveda predeterminada:

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 y seeklink index path/to/file.md para un solo archivo utilizan un demonio residente cuando no se pasa --vault. El demonio mantiene el incrustador y el reranker opcional calientes en la memoria; en macOS esto aparece como un proceso Python local. Es solo local, utiliza un socket Unix y no abre un puerto de red ni llama a un servicio en la nube. Por defecto, se cierra después de 15 minutos de inactividad. seeklink index para toda la bóveda se ejecuta en el proceso para que el progreso permanezca en stderr y el resumen final Done: permanezca en stdout. seeklink status y seeklink get siempre permanecen en arranque en frío: el estado solo lee metadatos de SQLite y la obtención lee el archivo directamente desde el disco. Usa --no-daemon, SEEKLINK_NO_DAEMON=1 o un --vault PATH explícito cuando un script necesite una ruta de arranque en frío de una sola vez.

Los usuarios de MCP siguen el mismo primer paso: construye el índice con seeklink index --vault PATH antes de registrar el servidor MCP.

Salida

La salida de búsqueda de texto es estable:

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

• PATH es relativo a la raíz de la bóveda.

• LINE tiene índice 1 y apunta al fragmento que mejor coincide en el archivo actual.

• El código de salida es 0 para éxito, incluyendo sin resultados; 1 para errores de tiempo de ejecución de bóveda/configuración/archivo detectados por SeekLink; y 2 para errores de uso de línea de comandos por análisis de argumentos.

• Las puntuaciones son útiles para ordenar dentro de una consulta. No compares puntuaciones entre ejecuciones con reranker habilitado y deshabilitado.

Usa JSON cuando un agente necesite una salida estructurada:

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

Comandos comunes

Búsqueda

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

Opciones:

--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.

Obtención

Lee una ventana de archivo precisa sin usar la base de datos o el demonio:

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 imprime líneas comenzando en LINE. -C/--context imprime líneas antes y después de LINE, al estilo grep. Los escapes de ruta como ../.. son rechazados.

Estado

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

El estado informa los recuentos de índice, nombres de modelo, compatibilidad de configuración de índice, estado de WAL de SQLite y advertencias de frescura. No carga los modelos de incrustación o reranking.

Diagnóstico

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

El diagnóstico verifica Python, SQLite, la base de datos local, la compatibilidad del índice, el estado del demonio y la disponibilidad opcional de MLX. No descarga ni carga modelos, pero puede inicializar la base de datos/esquema local de SeekLink si falta.

MCP

El adaptador opcional del Protocolo de Contexto de Modelo (MCP) permite a los clientes agentes descubrir y llamar a las herramientas de solo lectura de SeekLink directamente. La CLI sigue funcionando de forma independiente; MCP es otra superficie para la misma ruta de recuperación, no un reemplazo.

seeklink mcp --vault PATH

Instálalo con seeklink[mcp]. Construye el índice con la CLI primero: seeklink index --vault PATH. El adaptador MCP es de solo lectura y expone cuatro herramientas: search, get, status y doctor. No expone index, no escribe notas, no usa HTTP/OAuth ni enruta a través del demonio de socket Unix. Ejecuta un servidor MCP por bóveda. search mantiene su resumen de texto compacto con rutas y anclajes de línea; las vistas previas de resultados permanecen en contenido estructurado para los agentes que las necesiten. status y doctor pueden inicializar o migrar el esquema local de SeekLink cuando un .seeklink/seeklink.db existente lo necesite, pero no indexan ni modifican notas Markdown. Si tu cliente MCP no hereda tu PATH de shell, usa la ruta absoluta de which seeklink en los ejemplos a continuación.

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"]
    }
  }
}

Indexación

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

La indexación de toda la bóveda omite archivos sin cambios por hash de contenido a menos que el índice almacenado se haya construido con un incrustador, dimensión vectorial o configuración de fragmentación diferente, en cuyo caso SeekLink reconstruye el contenido del índice derivado. La indexación de un solo archivo actualiza un archivo Markdown solo cuando la configuración del índice existente es compatible.

Demonio

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

Normalmente no necesitas iniciar el demonio manualmente. search y index de un solo archivo lo generan y reinician automáticamente cuando es apropiado, luego se cierra después de SEEKLINK_DAEMON_IDLE_TIMEOUT segundos de inactividad. El valor predeterminado es 900 segundos (15 minutos); establécelo en 0, off, false o no para mantener el demonio caliente hasta que se detenga.

index de toda la bóveda sigue ejecutándose en el proceso para la salida de progreso. Pasar --vault a search o index de un solo archivo fuerza una ruta de arranque en frío de una sola vez porque el demonio está vinculado a una bóveda al inicio. --no-daemon y SEEKLINK_NO_DAEMON=1 también fuerzan la misma ruta de arranque en frío. Usa seeklink daemon status para inspeccionar el proceso caliente y seeklink daemon stop para liberar su memoria inmediatamente.

Cómo funciona la búsqueda

SeekLink fusiona cuatro canales con Reciprocal Rank Fusion:

El incrustador predeterminado es jinaai/jina-embeddings-v2-base-zh a través de fastembed. La búsqueda de texto completo CJK utiliza un tokenizador FTS5 jieba cuando la compilación local de Python/SQLite puede registrarlo de forma segura; de lo contrario, SeekLink recurre al tokenizador de trigramas integrado de SQLite en lugar de bloquearse.

La dimensión vectorial predeterminada es 768. Los experimentos avanzados con incrustadores personalizados pueden establecer SEEKLINK_EMBEDDING_DIM, pero debe coincidir con la salida del incrustador y requiere una reconstrucción completa de seeklink index.

En Apple Silicon, SeekLink puede reordenar candidatos con mlx-community/Qwen3-Reranker-0.6B-mxfp8 cuando se instala con seeklink[mlx]. El reranking es local y opcional; si MLX no está disponible, SeekLink recurre a la clasificación RRF híbrida de primera etapa. Usa --no-rerank para una consulta o establece SEEKLINK_RERANKER_MODEL="" para deshabilitarlo globalmente.

Frontmatter

El frontmatter de Markdown es opcional. Cuando está presente, SeekLink lo usa para etiquetas y alias:

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

• tags admite búsqueda filtrada: seeklink search "memory" --tags ai

• aliases se indexan para la búsqueda y se usan al resolver wikilinks

Almacenamiento

SeekLink escribe una base de datos SQLite dentro de la bóveda:

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

La base de datos contiene metadatos de origen, fragmentos, tablas FTS5, vectores sqlite-vec y un grafo de wikilinks. Elimina .seeklink/ y ejecuta seeklink index para reconstruir.

Soportado

No para

• Búsqueda multiusuario alojada o sincronizada.

• Fuentes que no sean Markdown sin conversión.

• Una GUI o plugin de Obsidian.

• Búsqueda de sub-milisegundos sobre millones de notas.

• APIs de incrustación o reranking en la nube.

Notas para agentes

Los agentes pueden usar SeekLink a través de llamadas de subprocesos ordinarias:

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

Los clientes MCP pueden usar el adaptador opcional de solo lectura:

seeklink mcp --vault PATH

Para hacer que un agente elija SeekLink para una bóveda Markdown, agrega esto a AGENTS.md, CLAUDE.md o las reglas del editor del proyecto:

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.

Para bucles calientes, el demonio expone un protocolo JSON prefijado por longitud sobre el socket Unix en ~/.rhizome/seeklink.sock. La mayoría de los agentes deberían preferir la superficie JSON de la CLI a menos que necesiten específicamente latencia a nivel de socket.

Consulta llms.txt para el contrato compacto de agentes.

Evaluación

Las pruebas de calidad de búsqueda se encuentran en tests/blind/; el método está documentado en docs/blind-test.md. Las afirmaciones de lanzamiento deben estar respaldadas por las consultas de prueba incluidas o por mediciones de bóvedas privadas claramente etiquetadas.

Contribución

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

Mantén las dependencias de tiempo de ejecución pequeñas, mantén los documentos públicos orientados al usuario y agrega una entrada en CHANGELOG.md para cambios visibles para el usuario.

Licencia

MIT