Vault Loom

简体中文

Weave your vault into useful AI context. Vault Loom combines streaming chat, note-aware retrieval, editing commands, and a confirmation-gated agent mode for Obsidian.

Features

• Stream assistant responses and stop an active generation.
• Use the current selection or active note as structured context.
• Find relevant Markdown notes with keyword search.
• Optionally index Markdown chunks for embedding-based semantic retrieval.
• Preview the context attached to the latest request.
• Create, switch, restore, and delete chat sessions.
• Explain or rewrite a selection and summarize the current note from the command palette.
• Run a bounded Agent mode with visible tool activity and per-operation confirmation for note writes.
• Connect to configurable OpenAI-compatible chat and embedding endpoints.

Requirements and compatibility

• Desktop Obsidian 1.12.7 or later.
• An OpenAI-compatible endpoint and any credentials required by that endpoint.

The first public release is desktop-only. Mobile support may be enabled after the complete workflow has been verified on Obsidian mobile.

An endpoint may support chat completions without supporting streaming, tool calls, or embeddings. Chat mode only requires compatible chat completions; Agent mode requires tool-calling support, and semantic retrieval requires an embeddings endpoint.

Installation

Community Plugins

Vault Loom is available in the Obsidian Community Plugins directory. Install it from Settings → Community plugins inside Obsidian.

Manual installation from source

1. Install Node.js and clone this repository.

2. From the repository root, run:

   npm ci
   npm run build
   

3. Create a plugin folder inside your vault:

   <vault>/.obsidian/plugins/vault-loom/
   

4. Copy main.js, manifest.json, and styles.css into that folder.

5. Reload Obsidian, open Settings → Community plugins, and enable Vault Loom.

For a development vault, set OBSIDIAN_PLUGINS_DIR in .env.local and run npm run deploy:test. You can also pass the destination directly:

npm run deploy:test -- "<vault>/.obsidian/plugins"

Configuration

Open Settings → Vault Loom and configure:

Setting	Purpose	Default
API key	Credential stored in Obsidian plugin data	Empty
Base URL	OpenAI-compatible API base URL	https://api.openai.com/v1
Model	Chat completions model name	gpt-4o-mini
Embedding model	Model used for semantic retrieval	text-embedding-3-small
Temperature	Response randomness from 0 to 2	0.7
Context token budget	Estimated token budget for attached context	4000
Include selection	Prefer the active editor selection as context	On
Include current file	Use the active note when there is no selection	On
Include vault search	Attach keyword-matched note snippets	On
Include embedding retrieval	Index and retrieve semantically related chunks	Off

Use Test provider from the command palette to check the chat configuration.

Usage

Chat

Open the sidebar with the ribbon bot icon or Open chat from the command palette. Enter a prompt and select Send. Responses stream into the active session, and Stop cancels the current request.

The context preview shows which selection, current note, keyword matches, or semantic matches were attached. Context is estimated and trimmed to the configured budget before prompt composition.

Chat sessions are stored in Obsidian plugin data and restored after the plugin reloads. Creating, switching, and deleting sessions does not modify Markdown notes.

Editing commands

Command	Result
Explain selection	Inserts an explanation for the selected text
Rewrite selection	Replaces the selected text with a rewrite
Summarize current note	Inserts a summary into the active editor

Running one of these commands is the explicit action that authorizes its editor change. If the request fails, the command does not write generated text.

Agent mode

Select Agent in the Vault Loom sidebar to allow the model to request registered tools. Agent execution is sequential and bounded, and tool activity remains visible in the conversation.

Tool	Access	Behavior
search_vault	Read	Searches Markdown note names and content
read_note	Read	Reads one vault-relative Markdown note
create_note	Write	Creates a new note without overwriting an existing one
append_to_note	Write	Appends Markdown to an existing note
replace_selection	Write	Replaces the current non-empty editor selection

Every write tool displays a preview and requires approval before it runs. If the active note or selection changes while a replacement is awaiting approval, the replacement is rejected.

Privacy and data handling

This plugin connects directly from Obsidian to the API base URL you configure. Review the privacy and retention terms of that service before sending sensitive vault content.

• The API key, settings, chat history, and optional embedding index are stored in Obsidian plugin data.
• Chat requests may send the conversation plus enabled selection, current-note, keyword-search, and semantic-search context to the configured provider.
• When semantic retrieval is enabled, Markdown chunks are sent to the configured embeddings endpoint. Their text, metadata, and returned vectors are stored in the local plugin data index.
• Agent requests may send tool definitions, tool arguments, and tool results to the configured provider.
• Read tools do not change vault files. Editing commands and Agent write tools only write after an explicit user action or confirmation.
• The project does not implement telemetry or analytics.

Development

npm ci
npm run dev

Before submitting a change, run the same automated quality gate used by the project:

npm run verify

npm run verify checks formatting, linting, TypeScript, the production build, unit tests, release metadata, and required release assets. Local Obsidian smoke testing is separate and can be prepared with npm run deploy:test.

The codebase keeps UI, provider execution, Obsidian adapters, structured context, prompt composition, retrieval, and tools in separate modules. See the implementation plan, stage status, and architecture decisions for details.

Release status

Vault Loom is available in the Obsidian Community Plugins directory. The latest release is published on GitHub with the required Obsidian assets. See the release guide for the release process.

License

Vault Loom is available under the MIT License.