연결된 노트 (Open Connections)

당신의 노트를 의미론적으로 연결합니다. 관련 노트를 발견하고 전체 볼트에서 의미론적 검색을 가능하게 하는 강력한 Obsidian 플러그인입니다. 로컬 임베딩 또는 선호하는 AI 제공업체를 통해 작동합니다.

License

Desktop Only

Open Connections를 사용해야 하는 이유?

Open Connections는 단순 키워드 검색과 지능형 의미론적 발견 사이의 간극을 메웁니다. Obsidian에서 글을 쓰는 동안, 현재 파일과 의미론적으로 관련된 노트를 자동으로 표시합니다. 단순히 키워드가 일치하는 것이 아니라 개념적으로 연결된 아이디어들입니다. 로컬 임베딩을 사용하거나 OpenAI, Gemini, Ollama 등 선호하는 제공업체와 원활하게 통합하여 전적으로 당신의 장치에서 작동합니다.

주요 기능 (Features)

• 기본값으로 로컬 임베딩 — API 키 없음, 설정 불필요. WebGPU 가속(WASM 폴백)을 사용하여 인브라우저에서 Transformers.js 실행
• 다중 제공업체 지원 — Transformers (로컬), OpenAI, Gemini, Ollama, LM Studio, Upstage 또는 OpenRouter 사용 가능
• 연결 보기 (Connections View) — 탐색하는 동안 관련 노트를 확인합니다. 파일을 열 때 자동으로 업데이트됩니다.
• 의미론적 검색 (Semantic Lookup) — 키워드가 아닌 의미로 볼트를 검색합니다. 찾고 있는 것을 즉시 발견할 수 있습니다.
• 다국어 지원 — 로컬 모델에는 비영어권 볼트를 위한 다국어 변형이 포함되어 있습니다.
• 개인 정보 보호 우선 (Privacy-first) — 로컬 임베딩을 사용할 때 당신의 노트는 장치를 벗어나지 않습니다.
• 빠른 SQLite 캐시 — 임베딩은 로컬에 저장되며 세션 전반에 걸쳐 재사용됩니다.
• 모델 지문 인식 (Model fingerprinting) — 제공업체나 모델을 변경할 때 자동으로 다시 임베딩합니다.
• 상태 표시줄 진행률 — 실시간으로 임베딩 진행 상황을 확인할 수 있습니다.
• 모바일 지원 — iOS 및 Android에서 작동합니다.

빠른 시작 (Quick Start)

설치 (Installation)

커뮤니티 플러그인 브라우저에서 (권장)

1. Obsidian을 열고 설정 > 커뮤니티 플러그인으로 이동합니다.

2. 안전 모드가 활성화되어 있다면 비활성화합니다.

3. **탐색(Browse)**을 클릭하고

4. 최신 릴리스에서 main.js, manifest.json, 그리고 styles.css를 다운로드합니다.

5. 볼트(vault) 내에 .obsidian/plugins/open-connections/ 폴더를 생성합니다.

6. 세 개의 파일을 해당 디렉터리에 복사합니다.

7. 설정(Settings) > 커뮤니티 플러그인(Community Plugins)에서 Open Connections를 활성화합니다.

소스에서 빌드하기 (Build from Source)

git clone https://github.com/GoBeromsu/Open-smart-connections.git
cd open-connections
pnpm install
...

dist/의 내용을 볼트의 .obsidian/plugins/open-connections/ 디렉터리로 복사합니다.

동일 레포지토리/패키지에서 MCP 사용하기 (MCP Usage from the Same Repo/Package)

Open Connections는 이 동일한 저장소/패키지에서 두 가지 방식으로 MCP 지원을 제공합니다:

1. Obsidian 내부 — 설정(Settings) → Open Connections → MCP를 활성화하고 로컬 서버를 시작하거나, 기존 명령어 팔레트 액션을 실행합니다:
   • Open Connections: Start local server
   • Open Connections: Stop local server
2. 독립형 CLI (Standalone CLI) — 패키징된 bin 엔트리를 사용합니다:

pnpm install
pnpm exec open-connections-mcp /path/to/your/vault

HTTP 모드도 사용할 수 있습니다:

pnpm exec open-connections-mcp /path/to/your/vault --http --port 27124

독립형 프로세스는 볼트 플러그인 데이터를 .obsidian/plugins/open-connections/에서 읽기 때문에, 대상 볼트에 대해 플러그인이 이미 설치되어 있고 최소 한 번 실행되었어야 합니다.

첫 단계 (First Steps)

1. 설정(Settings) > Open Connections를 엽니다.
2. 임베딩 제공업체(embedding provider)를 선택합니다 (기본값: Transformers local).
3. 드롭다운에서 모델을 선택합니다.
4. API 제공업체의 경우, API 키를 입력합니다.
5. 리본 아이콘에서 Connections 뷰를 엽니다.
6. 볼트를 탐색하기 시작하면 관련 노트가 자동으로 나타납니다.

작동 방식 (How It Works)

**임베딩(Embeddings)**은 시맨틱 검색의 핵심입니다. 이는 텍스트를 의미를 포착하는 수학적 벡터로 변환합니다. Open Connections는 이 벡터들을 사용하여 의미적으로 유사한 노트를 찾습니다.

┌─────────────────┐
│  당신의 노트     │
└────────┬────────┘
...

두 가지 주요 뷰 (Two Main Views)

연결 보기(Connections View) — 현재 보고 있는 파일과 의미적으로 관련된 노트를 보여줍니다. 탐색함에 따라 자동으로 업데이트됩니다.

검색어 보기(Lookup View) — 전체 볼트에서 의미 기반 검색을 수행합니다. 키워드뿐만 아니라 의미로 노트를 찾으려면 쿼리를 입력하세요.

임베딩 제공업체 (Embedding Providers)

Open Connections는 여러 임베딩 제공업체를 지원합니다. 워크플로우에 가장 적합한 것을 선택하세요:

권장 구성 (Recommended Configurations)

개인 정보 보호에 가장 좋음 (로컬, 설정 없음):

Provider: Transformers
Model: Xenova/bge-micro-v2 (기본값, 빠름, 좋은 품질)

품질에 가장 좋음 (API):

Provider: OpenAI
Model: text-embedding-3-small 또는 text-embedding-3-large

다국어 볼트에 가장 좋음 (로컬):

Provider: Transformers
Model: Xenova/bge-m3 (다국어, 고품질)

다국어 볼트에 가장 좋음 (API, 무료 등급):

Provider: Gemini
Model: gemini-embedding-001

자체 호스팅에 가장 좋음 (로컬 서버):

Provider: Ollama
Model: nomic-embed-text 또는 bge-m3 (다운로드 후)

사용법 (Usage)

연결 보기 (Connections View)

1. 볼트에서 아무 노트나 엽니다.
2. 연결 보기(Connections View)가 자동으로 관련 노트를 보여줍니다.
3. 결과 중 하나를 클릭하여 해당 노트로 이동합니다.
4. 파일 간을 탐색함에 따라 결과가 업데이트됩니다.

팁: 작업하는 동안 항상 의미 기반 검색이 가능하도록 사이드바에 연결 보기를 고정하세요.

검색어 보기 (Lookup View)

1. 리본 또는 명령 팔레트에서 검색어(Lookup) 보기를 엽니다.
2. 일반 언어로 쿼리를 입력합니다 (예:

• Open Connections: Open Connections View — 연결(Connections) 패널 표시
• Open Connections: Open Lookup View — 조회(Lookup) 패널 표시
• Open Connections: Re-embed all notes — 볼트 전체 재임베딩 강제 실행 (프로바이더/모델 변경 후 유용)
• Open Connections: Open settings — 플러그인 설정으로 이동

구성 (Configuration)

설정 탭 (Settings Tab)

임베딩 프로바이더 (Embedding Provider) — 임베딩이 가져올 출처 선택 (로컬 또는 API).

모델 선택 (Model Selection) — 플러그인이 선택한 프로바이더에서 사용 가능한 모델을 자동 감지합니다. API 프로바이더의 경우, 먼저 API 키를 설정해야 합니다.

연결 개수 (Connection Count) — 연결 뷰에 표시할 관련 노트 개수 (기본값: 5).

API 키 (API Keys) — OpenAI, Gemini, Upstage, OpenRouter 등의 자격 증명을 저장합니다. 키는 Obsidian의 암호화된 설정에 저장됩니다.

고급 (Advanced) — 모델 지문(Model fingerprinting), 캐시 관리, 재임베딩 트리거.

환경 변수 (Environment Variables)

개발 또는 고급 구성을 위해 .env 파일에 다음을 설정합니다:

OPENAI_API_KEY=your-key-here
GEMINI_API_KEY=your-key-here
OLLAMA_HOST=http://localhost:11434

기술 스택 (Tech Stack)

open-connections/
├── src/
│   ├── main.ts                   # 플러그인 진입점
... 

개발 (Development)

전제 조건 (Prerequisites)

• Node.js 18+ (권장: 22+)
• pnpm 10+
• Obsidian 테스트 볼트

설정 (Setup)

git clone https://github.com/GoBeromsu/Open-smart-connections.git
cd open-connections
pnpm install

개발 명령어 (Development Commands)

pnpm dev              # 볼트 선택 + esbuild watch + 핫 리로드
pnpm build            # dist/로 프로덕션 빌드
pnpm test             # 단위 테스트 실행 (Vitest)
... 

핫 리로드 (Hot Reload)

pnpm dev는 Obsidian의 핫 리로드 기능을 사용합니다. 변경 사항을 적용한 후:

1. 플러그인이 자동으로 재빌드됩니다 (esbuild watch)
2. 테스트 볼트가 새로고침됩니다 (올바르게 구성된 경우)
3. Obsidian을 다시 시작할 필요 없이 변경 사항이 즉시 나타납니다

Provider 런타임 검증 (테스트 볼트)

Provider 분류 작업을 위해, 대상 provider를 이미 .obsidian/plugins/open-connections/data.json에 구성한 전용 Test 볼트를 유지하고 다음을 실행하세요:

pnpm run verify:test-vault                                  # 일반 플러그인 새로고침 + 오류 스모크 검사
bash scripts/check-provider-runtime.sh upstage embedding-passage 4096
bash scripts/check-upstage.sh                               # 더 긴 Upstage 임베딩 실행

check-provider-runtime.sh는 빠른 provider 스모크 프로브입니다: 플러그인을 재빌드하고, Obsidian에서 새로고침하며, 광범위한 이슈 분류 또는 스모크 매트릭스 작업으로 넘어가기 전에 활성 어댑터/모델/차원, embed_ready, 및 개발자 오류 표면을 검증합니다.

기여하기 (Contributing)

기여를 환영합니다! 다음 단계를 따르세요:

1. 저장소를 포크(Fork)하세요
2. 기능 브랜치를 생성하세요: git checkout -b feature/your-feature-name
3. 커밋 메시지는 Conventional Commits를 따르세요
4. 변경 사항을 검증하려면 pnpm run ci를 실행하세요
5. 명확한 설명과 함께 풀 리퀘스트(pull request)를 제출하세요

참고: 이 플러그인은 생태계 내의 다른 Obsidian 플러그인들과 공유 아키텍처를 유지합니다. 큰 변경 사항은 먼저 이슈에서 논의되어야 합니다.

문제 해결 (Troubleshooting)

플러그인이 활성화되지 않거나 시작 시 충돌하는 경우

1. Obsidian 콘솔(Ctrl+Shift+I / Cmd+Shift+I)을 확인하세요
2. 지원되는 Obsidian 버전(1.1.0 이상)인지 확인하세요
3. 다른 임베딩 관련 플러그인을 비활성화해 보세요
4. .obsidian/plugins/open-connections/를 삭제하여 플러그인을 재설치하고 커뮤니티 플러그인에서 다시 활성화하세요

임베딩이 느리거나 CPU 사용량이 많은 경우 (로컬 Transformers.js)

1. 더 작은 모델 사용 시도: bge-m3 대신 Xenova/bge-micro-v2 사용
2. 할당량(quota)이 있다면 API 제공업체로 전환
3. 브라우저가 WebGPU를 지원하는지 확인 (지원되는 장치의 Chrome/Edge 사용); 그렇지 않으면 WASM 폴백을 사용합니다.

API 제공업체에서 오류 반환 시

1. API 키가 올바른지 확인하십시오 (제공업체 문서를 확인하세요)
2. 남아 있는 API 할당량을 확인하십시오
3. 특정 오류 메시지를 위해 Obsidian 콘솔을 확인하십시오
4. 테스트를 위해 다른 제공업체로 일시적으로 전환해 보십시오

결과가 관련성이 없어 보일 때

1. 임베딩 품질은 모델과 콘텐츠에 따라 달라집니다
2. 다른 모델을 사용해 보세요 (예: bge-micro-v2에서 bge-m3로 전환)
3. 일반적으로 더 크고 고품질의 모델이 더 나은 결과를 제공합니다
4. 임베딩 모델이 작동할 수 있도록 노트에 충분한 콘텐츠가 있는지 확인하십시오.

라이선스

GNU General Public License v3.0 (GPL-3.0)

자세한 내용은 LICENSE를 참조하십시오.

감사의 글

본 프로젝트는 Brian Petro가 만든 Smart Connections의 포크(fork)입니다. 안정성, 확장성 및 광범위한 Obsidian 플러그인 생태계와의 통합을 위해 처음부터 재구축되었습니다.

GPL-3.0 섹션 5에 따라, 이 수정된 버전은 원본과 다름을 명확히 표시합니다.

링크

• 리포지토리: https://github.com/GoBeromsu/Open-smart-connections
• 릴리스: https://github.com/GoBeromsu/Open-smart-connections/releases
• 이슈: https://github.com/GoBeromsu/Open-smart-connections/issues
• Obsidian: https://obsidian.md/
• Smart Connections (원본): https://smartconnections.app/

TypeScript로 빌드됨 · Transformers.js가 구동함 · Obsidian이 암호화함

커뮤니티 제출 체크리스트

obsidian-releases에 제출하기 전에, pnpm lint을 실행하여 모든 ObsidianReviewBot 위반 사항을 포착하십시오.