Sanyuan Context Router

Sanyuan Context Router is a desktop Obsidian client for an independently run Sanyuan retrieval sidecar. It sends an explicit query or editor selection to a user-configured endpoint, previews the returned read-injection block, and lets the user copy or insert it into the active note.

External sidecar required

This repository contains only the Obsidian thin client. Retrieval, embeddings, reranking, database access, and Sanyuan topology processing run in a separate Python sidecar. The plugin is not useful until that sidecar is installed and running.

The current reference sidecar (package sanyuan-obsidian 0.1.0) and its setup instructions live in the upstream Sanyuan Obsidian integration at the pinned commit b930c8dd (an immutable commit, not a mutable branch). That sidecar, the Sanyuan project, and its cognitive rules are separate works with separate licensing; they are not included in or licensed by this repository's MIT License.

Compatibility contract

• Sidecar API (sanyuan-obsidian 0.1.0): GET /health, POST /v1/should-retrieve, POST /v1/retrieve-and-inject.
• This release (0.1.1) ships the commands listed under Commands below.
• The browse-sanyuan-nodes command exists only on the upstream integration/obsidian branch and is not part of the 0.1.1 release. A client that requires that command must be built from the pinned commit above.
• Health checks must judge capability by contract version, not by assuming a command exists in every release.

Privacy and network disclosure

• No telemetry, analytics, advertising, or background vault scan.
• No request is made merely by loading the plugin.
• The default endpoint is http://127.0.0.1:8765.
• A non-loopback endpoint requires an explicit setting opt-in.
• When a retrieval command is invoked, the plugin sends the query text, current note path, and optional sanyuan_axes frontmatter to the configured endpoint.
• If a remote endpoint is enabled, that data leaves the device and is handled under the remote endpoint operator's policies.
• Embedding-provider credentials stay in the sidecar environment and are never stored by this plugin.
• An optional sidecar bearer token is stored in Obsidian's local plugin data.
• The plugin never reads the clipboard. Clicking Copy writes only the currently displayed injection block to the clipboard.

Commands

• Retrieve context always runs retrieval.
• Smart retrieve context runs only when the sidecar's conservative trigger recognizes an explicit retrieval intent.
• Check sidecar verifies connectivity and displays the detected status.

If the current editor selection is empty, the plugin asks for a query. Optional query axes can be declared in note frontmatter:

sanyuan_axes:
  - periodontitis
  - PNPLA8
  - fibroblast

Installation

After the plugin is accepted into the Obsidian Community directory, install it from Settings → Community plugins.

For manual installation, download main.js, manifest.json, and styles.css from the release whose tag matches the version in manifest.json. Put the three files in:

<vault>/.obsidian/plugins/sanyuan-context-router/

Restart Obsidian, enable the plugin, and configure the sidecar endpoint under Settings → Sanyuan Context Router.

Development

npm ci
npm run build

The production build creates main.js. The release workflow verifies that the manifest, package, and compatibility-map versions match, generates GitHub artifact attestations, then publishes main.js, manifest.json, and styles.css as release assets.

License scope

The source code and assets in this standalone repository are available under the MIT License. The Python sidecar, the upstream Sanyuan repository, and Sanyuan ontology or cognitive-rule materials are not part of this license.