SeekLink

English · 中文

SeekLink — это локальный CLI для семантического поиска и опциональный MCP-сервер (stdio) только для чтения для хранилищ Markdown. Он индексирует папку с файлами .md, выполняет поиск с помощью гибридного метода (ключевые слова + векторы) и возвращает результаты с привязкой к строкам, которые могут читать как люди, так и агенты с помощью простых команд оболочки.

Инструмент создан для персональных баз знаний, хранилищ, совместимых с Obsidian, двуязычных заметок (английский/китайский) и локальных рабочих процессов агентов. MCP-клиенты, такие как Claude Code, Cursor и VS Code, могут вызывать те же функции поиска/получения/статуса/диагностики через seeklink[mcp]. Это также полезный уровень поиска для паттернов Markdown-вики, таких как 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]"

Для клиентов Model Context Protocol (MCP), таких как Claude Code, Cursor или VS Code, установите дополнительный пакет 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 всегда выполняются с «холодного старта»: статус только считывает метаданные SQLite, а получение считывает файл напрямую с диска. Используйте --no-daemon, SEEKLINK_NO_DAEMON=1 или явный аргумент --vault PATH, когда скрипту нужен однократный запуск с холодного старта.

Пользователи MCP следуют тому же первому шагу: создайте индекс с помощью seeklink index --vault PATH перед регистрацией MCP-сервера.

Вывод

Вывод текстового поиска стабилен:

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

• PATH — путь относительно корня хранилища.

• LINE — номер строки (начиная с 1), указывающий на наиболее подходящий фрагмент в текущем файле.

• Код выхода 0 означает успех (включая отсутствие результатов); 1 — ошибки хранилища/конфигурации/файла, обнаруженные SeekLink; 2 — ошибки использования командной строки при разборе аргументов.

• Оценки (scores) полезны для сортировки в рамках одного запроса. Не сравнивайте оценки между запусками с включенным и выключенным переранжировщиком.

Используйте 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.

Получение (Get)

Чтение точного фрагмента файла без использования базы данных или демона:

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 и предупреждения об актуальности. Он не загружает модели эмбеддинга или переранжирования.

Диагностика (Doctor)

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

Doctor проверяет Python, SQLite, локальную базу данных, совместимость индекса, состояние демона и опциональную доступность MLX. Он не скачивает и не загружает модели, но может инициализировать локальную базу данных/схему SeekLink, если они отсутствуют.

MCP

Опциональный адаптер Model Context Protocol (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 сохраняет компактное текстовое резюме с путями и привязками к строкам; превью результатов остаются в структурированном контенте для агентов, которым это необходимо. status и doctor могут инициализировать или мигрировать локальную схему SeekLink, когда это требуется для существующего файла .seeklink/seeklink.db, но они не индексируют и не изменяют заметки Markdown. Если ваш MCP-клиент не наследует ваш системный 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 (RRF):

Эмбеддер по умолчанию — 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="", чтобы отключить его глобально.

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

Чтобы агент выбрал SeekLink для хранилища Markdown, добавьте это в 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.

Для «горячих» циклов демон предоставляет протокол JSON с префиксом длины через Unix-сокет по адресу ~/.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 для изменений, видимых пользователю.

Лицензия

MIT