obsidian-open-connections

Imported from Xia-Ataraxia/obsidian-open-connections (AGENTS.md). Install upstream with npx skills add Xia-Ataraxia/obsidian-open-connections. Copyright stays with the author.

open-connections

Purpose

Open Smart Connections — Obsidian plugin that uses local embeddings (Transformers.js via srcdoc iframe, WebGPU Metal-3 confirmed) to surface semantically related notes. Provides a Connections view (related notes) and Lookup view (semantic search). Embedding runs in-browser with no external API required.

Key Files

Subdirectories

For AI Agents

Working In This Directory

• 4-layer architecture enforced by ESLint no-restricted-imports: domain/, types/, utils/ must NEVER import obsidian
• Custom workspace events (e.g. open-connections:embed-progress) are typed in src/types/obsidian-augments.d.ts — no as any casts on event names
• Shared contracts, docs, and harnesses still come from obsidian-boiler-template, but runtime helper implementations now stay repo-local under src/ui/
• Embedding kernel (domain/embedding/kernel/) is now a slim barrel/types surface; queue and model helpers were flattened outward
• 3-phase initialization: Phase 1 (core, blocking), Phase 2 (embedding, background), Phase 3 (deferred block import via setTimeout 5s)
• UI is usable before Phase 2 completes; blocks are imported in Phase 3 background
• Vector search uses in-memory FlatVectorIndex when safe; oversized indexes must fall back to SQLite nearest-query behavior instead of risking memory blowups
• Large behavior-preserving refactors must land as very small checkpoint commits; do not mix wide file moves with logic changes
• Prefer tests/static enforcement as the main proof, and use obsidian-cli runtime smoke only for behavior that tests cannot fully prove (default vault for smoke: Test)
• WebGPU confirmed active (Metal-3, fp32) — [SC:GPU] diagnostic logging in EMBED_CONNECTOR, queryable via get_gpu_diag

Testing Requirements

pnpm run ci          # build + lint + test (must pass before any commit)
pnpm run test        # Vitest unit tests (382 tests, ~4s)
pnpm run typecheck   # tsc --noEmit
pnpm run lint        # ESLint — 0 errors required

Autoresearch Harness Scripts (Karpathy-style)

bash scripts/check-freeze.sh Test       # Plugin loads without UI freeze
bash scripts/check-webgpu.sh Test       # WebGPU backend active (Metal-3)
bash scripts/check-connections.sh Test  # 3 files show connections (50 results, <5s)
bash scripts/check-e2e.sh Test          # Full pipeline: sources + blocks + embedding

Each harness: build → deploy → boot Obsidian → eval check → PASS/FAIL. Freeze detection via eval timeout.

Common Patterns

// Workspace event (typed via augments — no as-any needed)
plugin.app.workspace.trigger('open-connections:embed-progress', payload);

// Private settings shape without any
(settings as unknown as { _connections_session?: SessionState })._connections_session

// EntityCollection — .all is already T[], no cast needed
const entities = this.block_collection.all; // EmbeddingBlock[]

Dependencies

Internal

• obsidian-boiler-template — source of truth for shared contracts, docs, and harnesses

External

• obsidian — Obsidian Plugin API
• @huggingface/transformers@3.8.0 — Transformers.js (CDN-loaded in srcdoc iframe, WebGPU Metal-3)
• node:sqlite — SQLite storage (Node built-in, Electron 39.5.1+)
• vitest — test runner