Agent LLMs

English | 한국어 | 日本語

This documentation describes 0.7.11. See the changelog for version history.

An AI assistant sidebar plugin for Obsidian with multi-provider backend support — AWS Bedrock, Google Gemini, OpenAI, and Ollama.

Note on command names: command palette entries, notices, the status bar, and tool results follow the UI language you pick in settings (English, 한국어, 日本語). Obsidian caches the palette at load time, so restart the app after switching languages to see the new names.

Features

• Multi-Provider AI Backend — Switch between AWS Bedrock (Claude), Google Gemini, OpenAI, and Ollama from settings
• Streaming Chat — Real-time streaming responses in the sidebar
• Graph RAG Vault Search — Chunk-level embeddings combined with link traversal (outlinks and backlinks) and a minimum relevance threshold
• Second Brain Layer — Opt-in knowledge layer (off by default) that can write wiki notes into a dedicated folder, with sentinel blocks that preserve your own notes
• Knowledge Gap Report — Finds structural gaps in the vault from index data alone (0 LLM calls)
• Hybrid Search — Lexical matches are fused with vector search by reciprocal rank fusion, so exact strings (error codes, function names, versions) are not lost to embedding similarity
• Filtered Search — The AI can narrow vault search by folder, tags, and modification date range
• Frontmatter Property Search — Filter by any frontmatter property with =, !=, >, >=, <, <=, and ~ (substring). Dot notation reaches nested keys, so project.status = active works. Invalid filters are reported rather than silently dropped, so a bad condition never masquerades as a whole-vault search
• AI Change Ledger & Safe Undo — Every note-changing AI action is recorded with a before/after snapshot (last 20). Undo restores the snapshot only if you have not edited the file since — if you have, that file is skipped rather than overwritten
• Attachment RAG — .txt, .csv, .json, and .html files in your vault are indexed and searchable alongside notes, not just read once and discarded
• Source Provenance — Synthesis notes record a content hash per source chunk. When a source changes, the note is marked outdated, and regenerating shows a diff of what changed
• Bases Dashboard — Generates a .base file with four views (decision ledger, open questions, outdated knowledge, review queue) from your vault data. Files you wrote yourself are never overwritten
• Citation Verification — Cited note paths and #heading anchors are checked against the index; unresolved citations are flagged under the answer
• Contradiction Review — Approve contradiction fixes note by note; only the generated region is replaced (0 LLM calls to apply)
• Link Suggestions — Proposes links for orphan and stub notes from index embeddings (0 LLM calls)
• Duplicate Candidates — Finds notes covering the same subject and proposes a canonical note plus aliases; nothing is deleted or merged (0 LLM calls)
• Decision Ledger — Collects scattered decisions with rationale, owner, deadline, and sources; superseded decisions are marked rather than deleted
• Inbox Triage — Suggests titles, folders, and tags for newly captured notes; renames go through Obsidian's link-preserving API
• Review Queue — Resurfaces 5 notes you have not opened in a while but that are well linked (0 LLM calls)
• Conversation Harvest — Extracts conclusions, decisions, rationale, and open questions from a saved chat session into a searchable note
• Reasoning Effort — Set reasoning depth per model; omitted on models that do not support it
• Auto Tag Generation — Analyze note content and suggest relevant tags
• Templates — Custom templates with variable substitution
• To-Do Management — Daily to-do, automatic carry-over of incomplete items, archiving
• Archive Cleanup — Clean up old archived files from the settings tab
• P.A.R.A Organizer — Set up the P.A.R.A folder structure (Projects, Areas, Resources, Archives) and use AI to classify existing notes
• Web Clipper — Fetch, translate, and summarize web pages as markdown notes
• MCP Server Integration — Model Context Protocol servers (uvx, Docker)
• File Management — Create, edit, move, and delete notes through AI
• Multilingual UI — English, 한국어, 日本語. Settings, sidebar, command palette, notices, status bar, tool results, and error messages all follow your choice
• File Attachments — Drag-and-drop, clipboard, file search. Images work on all four backends; PDFs on Bedrock and Gemini; Office documents on Bedrock. Unsupported combinations are refused with the list of backends that can handle the format, rather than dropped silently
• Chat Session History — Save and restore past conversations
• Obsidian Skills — Six built-in knowledge modules: obsidian-markdown, obsidian-bases, json-canvas, korean-writing, business-english-writing, second-brain
• Chat Retrospective — Type "회고", "retrospective", or "振り返り" in chat to auto-generate a daily retrospective, chained with the retrospective sections of the last 7 days so recurring problems stay visible
• Chat Export — Export conversations as markdown files
• Response Regeneration — Regenerate the last AI response
• Conversation Search — Search through saved chat sessions
• MCP JSON Editor — Real-time validation, auto-formatting, bracket matching, and templates
• Note Change and MCP Tool Confirmation — Optional approval before file-changing tools and every MCP tool call
• Context Window Management — Automatic token trimming

Installation

Requires Obsidian 1.7.2 or later, on desktop.

Obsidian 1.13+ settings search can find the settings shown for the current backend. Earlier Obsidian versions retain the settings screen.

BRAT (Recommended)

1. Install the BRAT plugin
2. Add this repository URL in BRAT settings: https://github.com/teinam/obsidian-agent-llms
3. Enable the plugin

Manual

1. Download main.js, styles.css, manifest.json from the latest Release
2. Copy to .obsidian/plugins/agent-llms/
3. Enable in Settings → Community Plugins

Upgrading from an earlier version

Version 0.4.0 changes the plugin ID from ai-assistant to agent-llms. The old ID was already claimed by an unrelated plugin in Obsidian's community plugin registry (qgrail/obsidian-ai-assistant), so Obsidian's updater treated this plugin's folder as that one and overwrote it. Nobody else has registered the new ID.

• Disable the old plugin before enabling the new one. If both are enabled simultaneously, the old plugin's index save can interleave with the new plugin's migration read, resulting in a torn copy (this self-heals through re-indexing but takes time).
• The plugin folder changes, so reinstallation is required. If you use BRAT, remove the old entry and add it again. Leave the old folder in place until the migration notice appears — that is where your settings are copied from.
• Settings (data.json), vault index, chat history, sessions, MCP config, and credentials are automatically copied on first launch. Your backend choice, models, region, Second Brain settings, and custom skills are all preserved. The old files remain in place, so rolling back to a previous version works seamlessly.
• You must reopen the sidebar once. Obsidian records view identifiers in the workspace layout, and the plugin cannot rewrite that for you.
• A notice appears once the migration completes. Then delete .obsidian/plugins/ai-assistant/ — if the overwriting update already ran, that folder holds an unrelated plugin's code rather than this one. The old data files (.ai-assistant-*.json, .bedrock-assistant-*.json) are no longer used either; you may delete them manually if vault size is a concern. The index file can be tens of MB due to embeddings.

If you were using the kiro-edition (Assistant Kiro), the same migration applies. That edition was merged into main in 0.3.0, and .assistant-kiro-*.json data is also migrated automatically.

Quick Start

1. Choose AI Backend

Settings → Agent LLMs → AI Backend:

• Bedrock — AWS Bedrock (Claude and other Bedrock-hosted models)
• Gemini — Google Gemini. Requires an API key from Google AI Studio.
• OpenAI — OpenAI or any OpenAI-compatible endpoint
• Ollama — A local Ollama server

The sidebar icon, model list, and branding update dynamically when you switch.

Backend support policy: This plugin relies on embedding APIs for Graph RAG vault search, so only providers with embedding endpoints are supported. The Anthropic direct API is excluded because it offers no embedding endpoint — use the Bedrock backend to access Claude models.

2. Configure Credentials

Bedrock: Enter a Bedrock API key (AWS Console → Bedrock → API keys) and set the AWS Region. The plugin does not refresh the key automatically; replace it when it expires.

Key issuance, model access, and using multiple machines: Bedrock setup guide

AWS access key and ~/.aws profile (including SSO) authentication were removed in 0.3.0. This backend uses the Bedrock API key entered in settings.

Required IAM permissions:

• bedrock:InvokeModelWithResponseStream
• bedrock:InvokeModel
• bedrock:ListFoundationModels
• bedrock:ListInferenceProfiles
• bedrock:CallWithBearerToken

Gemini: Enter your API key from Google AI Studio.

OpenAI: Enter your API key. To use an OpenAI-compatible endpoint, set the base URL including /v1; leave it empty for the official API.

Ollama: Enter the server base URL, or leave it empty to use http://localhost:11434. No API key is needed.

Key storage: Successfully saved keys are encrypted with the OS keychain and excluded from vault sync. Configure each device separately. Legacy keys in data.json are removed only after local storage succeeds; if saving fails, resolve the issue and save again before restarting.

3. Open the Sidebar

Click the ribbon icon, or run the command Open assistant from the command palette.

4. Index Your Vault (Optional)

Click 🔍 in the chat header to index notes for semantic search, or run Index vault. Indexing is required for Graph RAG search and for the Second Brain tools that search the vault. emerge needs the index too, because it enumerates index entries. architect and update_index read the vault file list directly and work without an index.

Usage

Chat

Type a message in the input area and press Enter. The AI responds in real-time streaming. Attach notes for context using the toolbar buttons:

• 📎 Attach current note
• 🔍 Search and attach any file
• 📁 Attach images/PDFs via file picker, drag-and-drop, or clipboard paste

The web search toggle (globe icon) in the input toolbar only turns on if a search MCP (fetch, exa, or brave) is configured, or if you are on the Gemini backend, which has native Google Search grounding. Otherwise clicking it shows a notice and the toggle stays off.

Reasoning Effort

Settings → Agent LLMs → Generation Settings → Reasoning Effort sets how much reasoning the model does.

Allowed values depend on the selected provider and model (for example, Anthropic models on Bedrock accept xhigh and max; Gemini Pro models accept only low and high). The setting is only shown for models that support reasoning effort, and requests to models that do not support it fall back to the provider's default sampling behavior. If you switch to a model that does not allow your saved value, it is clamped to the nearest allowed level.

Graph RAG Vault Search

Notes are split into chunks and embedded, then a search walks outlinks and backlinks from the best matches to pull in related neighbours. Start indexing from the search icon in the sidebar header, or the Index vault command. Edited files are re-indexed automatically.

Details: Graph RAG & Second Brain

Second Brain Layer

A layer that creates and maintains wiki notes grounded in your existing notes. It is off by default — enable it explicitly under Settings → Second Brain.

• Read-only tools (challenge, connect, emerge, reconcile) never create notes; they only return analysis.
• Generation tools (synthesize, architect, and others) write only inside the wiki folder you configure.
• Generated regions are wrapped in <!-- @generated:KEY --> markers, so regenerating keeps any notes you wrote yourself in the same file.

Details: Graph RAG & Second Brain

Web Clipper

Click the globe icon (🌐) in the action toolbar above the chat input → enter a URL. The page is fetched, translated (if needed), and summarized as a markdown note.

The generated frontmatter has four fields: source (the URL), created (the date), type: web-clip, and tags: [web-clip].

To-Do & Archive

• To-Do: Generates a daily note from a template with {{date}} / {{prevDate}} variables
• Carry-over: Incomplete tasks from the previous day are carried over with hierarchy preserved
• Auto archive: Old to-do files move to the archive folder
• Archive cleanup: Delete old archived files from the settings tab (configurable folder and day threshold)

P.A.R.A Organizer

1. Open Settings → Agent LLMs and scroll to the Vault section
2. Click the Set Up P.A.R.A button, directly below the Template Folder setting
3. The plugin creates four root folders: 01. Projects, 02. Areas, 03. Resources, 04. Archives
4. If existing notes are found, the currently configured AI model classifies each note into the appropriate folder
5. A progress modal shows real-time status and a summary when complete

MCP Server

Settings → MCP Servers → Edit Config:

{
  "mcpServers": {
    "fetch": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/fetch"]
    }
  }
}

Both uvx (Python) and docker are supported.

Declare API keys, proxies, DOCKER_HOST, and other server-specific values in that server's env; the full parent environment is no longer inherited. These values are stored in the vault's .obsidian/plugins/agent-llms/mcp.json, so manage that file's sync scope when it contains secrets. This is separate from local encrypted storage of AI backend keys.

Enable Confirm note changes and MCP tools to review the tool name and input before every MCP call (off by default). Stop all also cancels servers that are still initializing.

Network Usage

This plugin makes network requests to the following external services:

• AWS Bedrock API — When using the Bedrock backend, requests are sent to AWS Bedrock endpoints for chat, embedding, and model listing. The specific region endpoint depends on your configured AWS Region (e.g., bedrock-runtime.us-east-1.amazonaws.com).
• Google Gemini API — When using the Gemini backend, requests are sent to generativelanguage.googleapis.com for chat, embedding, and model listing.
• OpenAI API — When using the OpenAI backend, requests are sent to https://api.openai.com/v1 for chat, embedding, and model listing, or to the OpenAI-compatible base URL you configure.
• Ollama — When using the Ollama backend, requests are sent to your Ollama server (default http://localhost:11434), which is local unless you point it elsewhere.
• Web Clipper — When using the Web Clipper feature, the plugin fetches the target URL to retrieve page content for summarization.
• MCP Servers — When MCP servers are configured, the plugin communicates with locally spawned MCP server processes via stdio.
• Sponsor banner — Opening the settings screen loads the sponsor button image from cdn.buymeacoffee.com.

No data is sent to any third-party analytics or tracking services.

System Access

These capabilities support the features below. MCP servers have their own access privileges.

• Process execution (child_process.spawn) — Saved MCP commands run on startup or reconnection with shell: false. The plugin does not insert a shell, but it does not sandbox the command or scripts supplied as arguments. No server configuration means no server process. A direct child that remains alive three seconds after stopping receives a force-kill signal.
• Filesystem access outside the vault (Node fs) — AI backend keys are encrypted in agent-llms-credentials.json under Electron's userData directory. A complete temporary file with mode 0600 replaces the destination; legacy credential files are copied within the same directory. Encryption/write failures preserve the previous file and show a notice. Legacy keys in data.json are removed only after local storage succeeds. Newly entered keys remain in memory if saving fails; resolve the issue and save again before restarting. MCP executable lookup uses Node's spawn and PATH.
• Environment variables — Only PATH, HOME, USERPROFILE, APPDATA, LOCALAPPDATA, SYSTEMROOT, SYSTEMDRIVE, COMSPEC, PATHEXT, TMPDIR, TMP, TEMP, LANG, LC_ALL, and LC_CTYPE are inherited by default. Per-server env overrides are then applied. Other tokens and runtime options are not passed automatically. A server controls how it uses or transmits values explicitly provided to it.
• Vault enumeration — Search, Graph RAG indexing, Second Brain, and file selection use Obsidian's file-list APIs. Indexing splits notes and supported text attachments into chunks and sends them to the configured embedding API. Attached notes and tool-read content can also enter model requests. Remote endpoints receive this content; local Ollama keeps these requests on the device.
• Clipboard — Written when you press a message's copy button and read when you paste into chat. Success appears only after the write completes; failures show a notice.

See the 0.7.11 review record (Korean) for changes and validation scope.

Verifying a release

Release assets from 0.7.6 onward carry GitHub artifact attestations, so you can confirm they were built from this repository:

gh attestation verify main.js --repo TeiNam/obsidian-agent-llms

Desktop Only

This plugin is desktop-only (isDesktopOnly: true) because MCP server integration relies on spawning local child processes via stdio, which is not available on mobile platforms.

License

MIT