Files

Contributor 5d5336757d feat: HaBraid v0.1.0 — host-following memory visualization engine for Obsidian

- Hybrid BM25 + HNSW vector search with context enrichment
- Knowledge graph with entities, relations, and community detection
- Host-following LLM route with fallback backends
- 3-tier lint system (static + HNSW dup + contradiction detection)
- Q&A Synthesis (Karpathy LLM Wiki pattern)
- 16 MCP tools for agent-driven workflows
- Incremental wiki generation with checkpointing
- SQLite-backed item store with FTS5 + vector indexes

2026-04-18 15:46:42 +09:00

3.7 KiB

Raw Blame History

PLAN: HaBraid Vector Search 추가

2026-04-16, Contributor

목표

HaBraid에 fastembed(ONNX) 기반 vector 임베딩을 추가하고, BM25(FTS5) + Vector 유사도를 RRF로 결합하는 하이브리드 검색 구현.

환경 제약

CPU-only (i5-9600K, AVX2), GPU 없음
RAM 8GB 중 ~1.2GB 사용 가능
Python 3.10, Node.js
디스크 16GB 여유

아키텍처

┌─────────────────────────────────────┐
│            hw_search                │
│  "한국어 쿼리"                       │
└─────────┬──────────────┬────────────┘
          │              │
    ┌─────▼─────┐  ┌─────▼──────┐
    │  BM25      │  │  Vector    │
    │  FTS5      │  │  fastembed │
    │  SQLite    │  │  ONNX      │
    └─────┬──────┘  └─────┬──────┘
          │               │
          │    RRF(k=60)  │
          └───────┬───────┘
                  ▼
           하이브리드 결과

모델 선택

BAAI/bge-small-en-v1.5 (기본) 또는 intfloat/multilingual-e5-small (한국어)

모델	차원	크기	한국어	속도
bge-small-en-v1.5	384	~130MB	❌	빠름
multilingual-e5-small	384	~470MB	✅	보통

→ 기본: multilingual-e5-small (한국어 지원이 필수)

구현 계획

1. Python 임베딩 서비스 (`scripts/embed.py`)

# stdin으로 JSON → stdout으로 JSON
# 모드: embed (텍스트 → 벡터), index (DB 아이템 전체 임베딩)
# 모델 첫 로드 후 캐시 (재실행 필요 없음)

Node.js에서 child_process로 실행. stdout/stdin JSON 통신.

2. SQLite 스키마 변경

-- 임베딩 캐시 (아이템당 1행)
CREATE TABLE IF NOT EXISTS item_vectors (
  item_id TEXT PRIMARY KEY REFERENCES items(id),
  vector BLOB NOT NULL,           -- Float32 array
  model TEXT NOT NULL DEFAULT '',  -- 모델명
  updated_at TEXT NOT NULL
);

-- 인덱스
CREATE INDEX IF NOT EXISTS idx_item_vectors_model ON item_vectors(model);

BLOB으로 384차원 float32 = 1536바이트/아이템. 503개면 ~750KB.

3. TypeScript 모듈

src/search/
├── bridge.ts      # Python 임베딩 프로세스 관리
├── vector.ts      # 벡터 저장/검색
└── hybrid.ts      # BM25 + Vector RRF 결합

4. 검색 플로우

1. 사용자 쿼리 → BM25 검색 (top N*3)
2. 사용자 쿼리 → 임베딩 → 코사인 유사도 검색 (top N*3)
3. RRF 결합: score = Σ 1/(k + rank), k=60
4. 정규화 + 상위 N개 반환

5. MCP 툴 변경

hw_search에 mode 파라미터 추가:

keyword (기본): BM25만
semantic: Vector만
hybrid: 둘 다 (기본값 변경 고려)

hw_index: 신규 — 전체 아이템 임베딩 인덱싱

작업 순서

pip install fastembed 설치
scripts/embed.py 작성
src/search/bridge.ts — Python 프로세스 통신
DB 스키마 업데이트 (item_vectors 테이블)
src/search/vector.ts — 벡터 CRUD
src/search/hybrid.ts — RRF 결합
MCP 핸들러 업데이트
빌드 + 테스트

의존성

Python: fastembed (ONNX Runtime 번들, PyTorch 불필요)
Node.js: 기존 의존성만 사용 (child_process, better-sqlite3)

완료 기준

pip install fastembed 정상 설치
embed.py로 임베딩 생성 가능
503개 아이템 임베딩 인덱싱 완료
hw_search로 하이브리드 검색 동작
BM25-only 폴백 (fastembed 없을 때)

3.7 KiB Raw Blame History