Agents

An agent is a chat that can actually look things up. Ask it a question and it searches your vault, reads what looks relevant, and answers with wikilinks back to the notes it used — so you can check its work.

An agent needs a chat model. See Connecting a provider.

What an agent has is covered on its own page: the skills that give it tools, the integrations that let it script other plugins, its memory, and any MCP servers it connects to.

Conversations are notes

Chats are stored as .chat files in your vault. They open in a sidebar split rather than replacing the note you’re reading, they sync with everything else, and they are indexed — so you can search for a conversation by what was said in it.

History is a tree, not a list. Editing an earlier message or regenerating a reply creates a branch rather than destroying what was there. You can explore an alternative line of questioning and still go back.

Embedding a chat in a note

Because a chat is a file, you can transclude one into any note:

![[My conversation.chat]]

The note renders the conversation inline, as a read-only transcript with the chat’s title and last-modified date. Click the title to open the real thing.

This is the payoff of conversations being notes rather than app state. When a chat contains the reasoning behind a decision, embed it in the project note instead of paraphrasing it — the record stays where you’ll look for it, and it updates when the conversation does.

Hovering a .chat link gives you the same preview without a modifier key.

A few properties worth knowing:

• Read-only. You can’t continue a conversation from inside an embed.
• It follows the active branch. The embed resolves the same branch the chat view would show, so an embedded chat and the open one agree.
• It re-renders when the chat changes, including while an agent is still working in it.
• It loads lazily. A skeleton appears immediately and the transcript swaps in once parsed, so embedding a long chat — or several in one note — doesn’t block the page from painting.

Built-in tools

These are the tools the agent can be given. Which ones it actually has depends on its enabled skills — see Skills.

Tool	What it does
search_notes	Search the vault (lexical, semantic, or hybrid)
list_directory	List folders and files
read_content	Read a note’s content
grep_notes	Find an exact substring or regex across notes
get_all_tags	List every tag in the vault
get_properties	Read frontmatter properties, or list all property keys
execute_javascript	Run JavaScript against the vault
manage_notes	Create, update, delete, and move notes — staged for review
fetch_url	Fetch a public web page as markdown
web_search	Search the web
manage_skills	Create, revise, or delete skills

Two more tools appear situationally: load_skill, which pulls in a skill’s full instructions on demand, and a delegation tool when an agent has subagents configured.

search_notes is not a second, weaker search. It runs the same ranking pipeline as the search modal you open yourself — the same strategies, the same filters, the same fusion — so the agent sees the results you would have seen. See Search. The one difference is the starting point: the agent searches lexically unless it asks for semantic or hybrid, and if no embedding index is ready, it’s told so in the result rather than being left to guess.

Tool names and descriptions are editable per agent, so you can rename a tool or sharpen its description if your model responds better to different wording.

Nothing is written without your approval

Every note mutation goes through a staging queue. The agent doesn’t write to disk — it proposes changes, which appear as an inline diff in the editor, and you accept or reject them.

The one exception is the agent’s memory folder, where writes auto-apply. That is opt-in and scoped to that folder alone. See Memory.

Caution

The agent is instructed never to claim a change has already been applied, because it hasn’t. If it tells you it edited a note, the edit is still sitting in the review queue.

Multiple agents

You can configure several agents, each with its own model, system prompt, enabled skills, tool overrides, and MCP servers. Switch between them per chat.

A practical split: a fast, cheap local model for everyday vault questions, and a frontier cloud model for work that needs real reasoning.

They run in parallel

Chats don’t queue behind each other. Start a slow research task in one chat, open another, and keep working — both agents run at once, on different models if you like.

Each chat owns its own session state, so an action in one can’t leak into another. A running chat is parked, not cancelled, when you navigate away from it: close the tab, keep reading your notes, and come back to a finished answer.

The status bar shows a clickable chip per running chat, which is how you get back to one you’ve navigated away from. Turn it off with Show active agents in status bar under Settings → Agents if you’d rather not see them.

Tip

Parallelism is bounded by whatever your provider allows. Several concurrent chats against one cloud account can hit rate limits — a local model and a cloud model side by side avoids that entirely.

Subagents

An agent can be given other agents as subagents, which it can delegate self-contained subtasks to. Each subagent runs with its own model, tools, and prompt, and returns only its result — so a long, noisy subtask doesn’t fill the main conversation’s context.

Delegating to a copy of itself is the common case: a clean-context worker for a task whose intermediate steps you don’t need to see.

Subagents also run in parallel: an agent can dispatch several tasks in a single turn and let them work simultaneously, rather than waiting for each in turn. Each one’s activity is nested under its own task card in the transcript, so you can follow what each is doing.

Delegation is one level deep. A subagent’s own subagents are ignored.

Attachments and multimodal

Drop files straight onto the chat to attach them — the whole chat pane is the drop target, not just the composer, and it outlines itself while you drag. Dragging works from inside Obsidian (the file explorer, search results, and other file lists) and from outside it (Finder, Explorer, your desktop). Pasting a file into the composer attaches it too.

Dragging a vault file attaches its content. That is different from typing a [[wikilink]], which adds a reference the agent can follow — so drag when you want the file itself in the conversation.

Accepted: txt, md, csv, json, pdf, and images (png, jpg, jpeg, gif, webp). Anything else is flagged during the drag rather than failing after it. Folders are skipped — drag the files inside them.

Vision and PDF support is resolved per model at runtime, not assumed from the provider. A model that accepts images will accept them without extra configuration; one that doesn’t won’t be offered the option. If you drag an image onto a model that has no vision support, the drop is refused up front and tells you to switch models, rather than being sent and rejected.

PDF text is extracted locally before anything is sent.

The system prompt is a note

Each agent’s system prompt lives in your vault at Agents/System Prompts/<Agent Name>/Base.md, and its memory instructions alongside it in Memory.md. They are ordinary notes — edit them in Obsidian like anything else.

The shipped defaults remain available for comparison: a diff view shows what you changed and lets you reset. If a plugin update changes a default you had customized, you get a notice rather than a silent overwrite.

Where the answer comes from

The assembled system prompt is the base prompt, plus memory instructions when memory is on, plus the descriptions of every enabled skill. Skill bodies are not included up front — they’re advertised by description and loaded on demand, so a dozen skills don’t cost you a dozen skill-bodies’ worth of context on every turn.