# Agent LLMs

![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)
![Obsidian](https://img.shields.io/badge/Obsidian-1.7.2%2B-7C3AED.svg)
![Platforms](https://img.shields.io/badge/Platforms-Desktop%20%7C%20Mobile-blue.svg)
![AWS Bedrock](https://img.shields.io/badge/AWS-Bedrock-FF9900.svg)
![Google Gemini](https://img.shields.io/badge/Google-Gemini-4285F4.svg)
![OpenAI](https://img.shields.io/badge/OpenAI-GPT-412991.svg)
![Ollama](https://img.shields.io/badge/Ollama-Local-000000.svg)
![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-CI%20%2B%20Release-2088FF.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/teinam)

[English](README.md) | [한국어](README-KR.md) | [日本語](README-JA.md)

This documentation describes **0.7.15**. See the [changelog](CHANGELOG.md) 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 (Desktop Only)** — 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. Text files such as `.md` and `.txt` work on all four backends; each sends up to its first 8,000 characters, and a cut is marked in the prompt and on the file chip. 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

Supports desktop, phones, and tablets with Obsidian 1.7.2 or later. Saving mobile API keys requires **1.11.4 or later**; older versions keep new keys only for the current session.

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](https://github.com/TfTHacker/obsidian42-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](../../releases)
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](https://aistudio.google.com/).
- **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](docs/bedrock-setup-en.md)

> 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](https://aistudio.google.com/).

**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:** Desktop uses an OS-keychain-backed local file; mobile uses Obsidian SecretStorage. New keys are kept out of the vault's `data.json`. Enter keys separately on each device.

Desktop encryption or file-write failures preserve the existing credential file and show a notice. Legacy keys are removed from `data.json` after successful local storage, except that mobile preserves unreadable desktop ciphertext for desktop migration and never uses it as an API key. Unsaved new keys remain available only for the current session. Check the mobile app version (1.11.4+) or desktop keychain/file access, then save again.

### 3. Open the Sidebar

Use the ribbon icon or run **Open assistant** from the command palette. Chat opens in the right sidebar on both desktop and mobile.

### 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

On desktop, press Enter to send. On mobile, Enter inserts a newline; use the send button or Ctrl/Cmd+Enter to send. The AI responds in real-time streaming. Attach notes for context using the toolbar buttons:

- 📎 Attach current note
- 🔍 Search and attach any file
- 📁 Attach text files (`.md`, `.txt`, …), images, and PDFs from your computer via file picker, drag-and-drop onto the input area, 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.

Mobile does not run local MCP servers, so this toggle is available only for Gemini's native web search.

### 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](docs/second-brain-en.md)

### 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](docs/second-brain-en.md)

### 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 (Desktop Only)

Settings → MCP Servers → Edit Config:

```json
{
  "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 (Desktop Only)** — 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

Process execution, filesystem access outside the vault, and MCP environment variables apply only on desktop. Mobile keys use Obsidian SecretStorage; vault and clipboard access are shared. 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 files and 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 [mobile support guide (Korean)](docs/mobile-support.md) for mobile behavior and validation, and the [0.7.14 review record (Korean)](docs/review-0.7.14.md) for earlier editing and attachment changes.

### Verifying a release

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

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

## Desktop and Mobile

Chat, vault search, note editing, Graph RAG, Second Brain, and to-do management share the same code on desktop and mobile. Local MCP server execution and MCP settings are desktop-only.

For Ollama on mobile, configure a server address reachable from that device; `localhost` refers to the phone or tablet itself. Keep the app in the foreground for long indexing or agent tasks. See the [device setup and testing guide (Korean)](docs/mobile-support.md).

## License

[MIT](LICENSE)