SeekLink

English · 中文

SeekLink은 마크다운 볼트를 위한 로컬 의미론적 검색 CLI이자 선택적 읽기 전용 MCP stdio 서버입니다. .md 파일 폴더를 인덱싱하고, 하이브리드 키워드 + 벡터 검색을 수행하며, 사람과 에이전트가 간단한 셸 명령어로 읽을 수 있는 라인 단위의 결과를 반환합니다.

개인 지식 베이스, Obsidian 호환 볼트, 영어/중국어 이중 언어 노트, 로컬 에이전트 워크플로우를 위해 구축되었습니다. Claude Code, Cursor, VS Code와 같은 MCP 클라이언트는 seeklink[mcp]를 통해 동일한 읽기 전용 검색/가져오기/상태/진단 인터페이스를 호출할 수 있습니다. 또한 Andrej Karpathy의 llm-wiki와 같은 마크다운 위키 패턴을 위한 유용한 검색 계층이기도 합니다. 에이전트는 기존 페이지를 검색하고, 정확한 라인 범위를 읽은 다음, 볼트를 호스팅 서비스로 전송하지 않고도 위키를 업데이트할 수 있습니다.

모든 작업은 로컬에서 실행됩니다. API 키가 필요 없습니다. 클라우드 검색 서비스도 없습니다. Obsidian 플러그인도 필요 없습니다.

설치

uv tool install seeklink
# or
pip install seeklink

Apple Silicon에서 리랭킹(reranking)을 지원하려면 선택적 MLX 추가 기능을 설치하세요:

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

Claude Code, Cursor 또는 VS Code와 같은 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 프로세스로 나타납니다. 이는 로컬 전용이며, 유닉스 소켓을 사용하고, 네트워크 포트를 열거나 클라우드 서비스를 호출하지 않습니다. 기본적으로 15분 동안 활동이 없으면 종료됩니다. 전체 볼트 seeklink index는 프로세스 내에서 실행되므로 진행 상황은 stderr에 표시되고 최종 Done: 요약은 stdout에 남습니다. seeklink status와 seeklink get은 항상 콜드 스타트 방식으로 작동합니다. 상태 확인은 SQLite 메타데이터만 읽고, 가져오기는 디스크에서 파일을 직접 읽습니다. 스크립트에서 일회성 콜드 스타트 경로가 필요한 경우 --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입니다.

• 점수는 단일 쿼리 내에서 정렬하는 데 유용합니다. 리랭커가 활성화된 실행과 비활성화된 실행 간의 점수를 비교하지 마십시오.

에이전트가 구조화된 출력을 필요로 할 때는 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 상태 및 최신성 경고를 보고합니다. 임베딩이나 리랭킹 모델을 로드하지 않습니다.

진단

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

진단 도구는 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를 사용하거나, 유닉스 소켓 데몬을 통하지 않습니다. 볼트당 하나의 MCP 서버를 실행하세요. search는 경로와 라인 앵커를 사용하여 텍스트 요약을 간결하게 유지하며, 결과 미리보기는 이를 필요로 하는 에이전트를 위해 구조화된 콘텐츠로 유지됩니다. status와 doctor는 기존 .seeklink/seeklink.db가 필요할 때 로컬 SeekLink 스키마를 초기화하거나 마이그레이션할 수 있지만, 마크다운 노트를 인덱싱하거나 수정하지는 않습니다. 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는 파생된 인덱스 콘텐츠를 다시 빌드합니다. 단일 파일 인덱싱은 기존 인덱스 설정이 호환되는 경우에만 하나의 마크다운 파일을 업데이트합니다.

데몬

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(RRF)을 사용하여 네 가지 채널을 융합합니다:

기본 임베더는 fastembed를 통한 jinaai/jina-embeddings-v2-base-zh입니다. CJK 전문 검색은 로컬 Python/SQLite 빌드가 안전하게 등록할 수 있는 경우 jieba FTS5 토크나이저를 사용하며, 그렇지 않으면 SeekLink는 충돌 대신 SQLite의 내장 트라이그램(trigram) 토크나이저로 대체합니다.

기본 벡터 차원은 768입니다. 고급 사용자 지정 임베더 실험은 SEEKLINK_EMBEDDING_DIM을 설정할 수 있지만, 임베더 출력과 일치해야 하며 전체 seeklink index 재빌드가 필요합니다.

Apple Silicon에서 SeekLink는 seeklink[mlx]로 설치된 경우 mlx-community/Qwen3-Reranker-0.6B-mxfp8을 사용하여 후보를 리랭킹할 수 있습니다. 리랭킹은 로컬에서 수행되며 선택 사항입니다. MLX를 사용할 수 없는 경우 SeekLink는 1단계 하이브리드 RRF 랭킹으로 대체됩니다. 쿼리당 --no-rerank를 사용하거나 SEEKLINK_RERANKER_MODEL=""을 설정하여 전역적으로 비활성화하세요.

프런트매터

마크다운 프런트매터는 선택 사항입니다. 존재할 경우 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를 실행하여 다시 빌드하세요.

지원 환경

지원하지 않는 항목

• 호스팅되거나 동기화된 다중 사용자 검색.

• 변환 없는 비 마크다운 소스.

• 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를 선택하도록 하려면 프로젝트의 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의 유닉스 소켓을 통해 길이 접두사가 붙은 JSON 프로토콜을 노출합니다. 대부분의 에이전트는 소켓 수준의 지연 시간이 특별히 필요한 경우가 아니라면 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