Semantix

Semantix

Semantix is a local-first semantic retrieval and serendipity engine for Obsidian. As you write, it automatically surfaces highly relevant notes (Related) and unexpected cross-domain conceptual connections (Discover) directly in a dual-stream sidebar.

English | 中文说明

---

English

Key Features

• Dual-stream Inspiration:
  • Related: Combines Vector embeddings and Full-Text Search (FTS) via Reciprocal Rank Fusion (RRF), refined with a Cross-Encoder reranker to surface directly relevant notes.
  • Discover: Relevance-gated candidate pool with duplicate suppression, relationship penalties, and Maximal Marginal Relevance (MMR) diversity to spark cross-topic serendipity.
• Real-time Writing Companion: Context gating, keystroke debouncing, stable card ordering, popover previews, and navigation to a uniquely matched passage in the current note source.
• Local-First & Private: All embeddings, indexing, and reranking run on your local machine. Notes never leave your device unless you explicitly configure a remote private server.
• Robust Vault Indexing: Strict vault isolation, incremental syncing on save, failure-safe index retention, and graceful error recovery.

Requirements

• Obsidian v1.7.2 or later.
• Desktop: Python 3.11+ with uv for running the local engine.

---

Installation

Method 1: Obsidian Community Plugins (Recommended)

1. Open Obsidian Settings > Community plugins.
2. Make sure Restricted mode is turned off.
3. Click Browse and search for Semantix.
4. Click Install, then click Enable.

Method 2: Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest GitHub Releases.
2. In your vault, navigate to .obsidian/plugins/ and create a folder named semantix.
3. Copy main.js, manifest.json, and styles.css into .obsidian/plugins/semantix/.
4. Reload Obsidian and enable Semantix under Community plugins.

---

Getting Started

1. Start the Local Engine

Semantix uses a lightweight local Python sidecar for embedding and retrieval. In your terminal:

cd engine
uv sync --locked
uv run uvicorn main:app --host 127.0.0.1 --port 8000

Note: On first run, the engine will automatically download the local embedding model (BAAI/bge-small-zh-v1.5) and reranker model (BAAI/bge-reranker-base). No note contents are uploaded. For offline environments, you can pre-download models:

cd engine
uv run python scripts/download_models.py

You can also enable Auto-start Local Engine in the plugin settings to have Obsidian launch the sidecar automatically on desktop.

2. Verify Connection & Build Index

1. Go to Obsidian Settings > Semantix.
2. Verify that the backend status displays Connected.
3. Under Index Management, click Build Full Index.
4. The plugin will index your Markdown vault in batches. Progress is shown in the settings tab and status bar.

3. Use the Radar Sidebar

1. Click the ribbon icon or run the command Semantix: Open Radar View (or Semantix: Open side view).
2. Position the Semantix sidebar where you prefer (e.g., the right sidebar).
3. Start editing or browsing notes! As your cursor moves and you type, Semantix automatically queries the engine and refreshes:
   • Related: Notes directly connected to your current paragraph.
   • Discover: Notes from other folders and topics that share deep conceptual echoes.
4. Hover over any card for a quick popover preview, or click to jump directly to the referenced note.
5. Scan whole note shows partial results as sections finish. Stop scan stops subsequent sections; an in-flight search may still finish. Failed or stopped scans keep results visibly incomplete. A separate notice identifies degraded retrieval when a search capability is unavailable.

Navigation uses the complete matched text, including Markdown formatting and line breaks. If the passage changed or appears more than once, Semantix opens the note and reports that it cannot locate the match reliably.

---

Privacy & Network Security

• Local-first by default: All note embeddings, indexing (LanceDB), and search run locally on 127.0.0.1.
• Zero telemetry: Semantix contains no trackers, telemetry, or third-party cloud LLM/AI services.
• Desktop process access: Local mode runs the configured Python/uv executable and stops the plugin-owned process tree. These operations pass arguments directly with shell execution disabled. Remote mode does not start local processes.
• Vault and clipboard access: Full indexing enumerates Markdown notes and applies your exclusion rules before reading them. The Vault ID copy button writes that ID to the clipboard only when clicked; the plugin does not read clipboard contents.
• Vault safety: The plugin never modifies, renames, or deletes your Markdown notes. Vector and FTS indexes are stored in the engine's external data directory.
• Optional Remote Mode: If you explicitly configure a remote engine URL, note contents will be sent to that address. Remote deployments require setting a SEMANTIX_API_TOKEN and managing TLS/network security.

---

Engine Environment Variables

---

Troubleshooting

• Engine Not Connected: Verify the engine is running and accessible at http://127.0.0.1:8000/health. Check that the port in plugin settings matches.
• Model downloading takes long: Check network access to HuggingFace or ModelScope. Pre-run scripts/download_models.py if needed.
• Port Conflict: If the configured local port is occupied, the plugin selects a free loopback port and saves the new Engine URL. Force Restart Engine only restarts its own process. Disable the older obsidian-semantix plugin before enabling this semantix plugin: both register the same legacy view type and cannot run together.

---

中文说明

Semantix 是面向 Obsidian 的本地语义检索与灵感发现插件，在写作过程中提供强相关内容（Related）和跨主题关联（Discover）。

当前版本：v0.11.2。桌面端本地 Sidecar 是主要工作流；代码中存在显式开启的移动端远程模式，其正式支持等级仍记录在 PROGRESS 中等待确认。

核心能力

• Related：Vector + FTS 双路召回，经可选 Cross-Encoder 精排输出高相关笔记。
• Discover：在相关性门控后排除 Related，通过关系特征和 MMR 提供不重复的跨主题线索。
• 整篇扫描：逐段展示并标明部分结果，可停止后续段落；已发送的请求可能继续完成。失败、停止与检索能力降级均有明确提示。
• 命中定位：按完整命中正文定位原始 Markdown 行；内容已变化或存在重复时打开笔记并提示，不猜测位置。
• 实时编辑体验：上下文门控、迟到响应丢弃、稳定卡片排序、悬浮预览与原文定位。
• 可靠索引：Vault 隔离、增量同步、失败文档保留旧索引、FTS 显式重建与有界重试。

隐私与网络边界

• 默认模式仅在本机插件与 127.0.0.1 Sidecar 之间传输笔记内容；模型推理和索引存储在用户控制的环境中完成。
• 首次运行可能从模型注册源下载 BAAI/bge-small-zh-v1.5 和 BAAI/bge-reranker-base。这不会上传笔记内容。
• 只有用户显式配置私有远程 Engine 时，笔记数据才会发送至该地址。远程部署必须配置 API Token，并由操作者负责 TLS 或可信网络边界。
• 插件不会修改、重命名或删除 Vault 内的 Markdown 原文；向量和 FTS 索引存储在 Vault 外部的 Engine 数据目录。
• 项目不包含遥测或第三方笔记处理服务。
• 桌面本地模式会运行配置的 Python/uv 程序并停止插件自己启动的进程树；这些操作直接传递参数并禁用 shell。远程模式不会启动本地进程。
• 全量索引会枚举 Markdown 笔记，并在读取前应用排除规则。Vault ID 的复制按钮仅在点击时写入该 ID，插件不读取剪贴板内容。

架构

Obsidian Plugin (TypeScript)
  editor context -> query gate -> HTTP API -> result stabilizer -> sidebar
                                      |
                                      v
Semantix Engine (Python/FastAPI)
  embedding -> Vector + FTS -> rerank -> Related / Discover -> LanceDB

插件与 Engine 是独立交付物：

• Obsidian 插件：根目录 manifest.json、versions.json、package.json；构建产物：main.js、styles.css。
• Engine：Python 3.11+、FastAPI、LanceDB、Sentence Transformers，位于 engine/ 目录。

详细边界和真实协议来源见 ARCHITECTURE。

快速开始

1. 启动 Engine

要求 Python 3.11+ 和 uv：

cd engine
uv sync --locked
uv run uvicorn main:app --host 127.0.0.1 --port 8000

健康检查地址为 http://127.0.0.1:8000/health。首次加载模型需要可访问模型注册源；离线环境可提前执行：

cd engine
uv run python scripts/download_models.py

2. 构建并安装插件

要求 Node.js 22：

npm ci
npm run build

将根目录 main.js、manifest.json、styles.css 复制到：

<vault>/.obsidian/plugins/semantix/

启用插件后配置 Engine 地址。桌面本地模式可选择自动启动；该选项默认关闭。

3. 建立索引

Engine 连接成功后，在设置页启动全量索引。插件按文档数和字符数分批发送，并在批次间让出 UI 执行权。失败文档保留在增量队列中重试。

---

文档导航

• ARCHITECTURE：范围、架构、数据流、协议、检索与不变量。
• PROGRESS：当前状态、版本履历、问题、阻塞和下一步。
• DECISION：不可变 ADR 与取舍。
• TESTING：验证层级、命令和行为门。

License

MIT