Notebrain

AI agent inside your Obsidian notes -- chat with DeepSeek directly in any note, with 21 tools for vault search, web research, academic papers, and more.

Features

• Chat inside any note -- Press Ctrl+Shift+Enter (macOS: Cmd+Shift+Enter) to start a conversation. The AI reads your note context and responds directly in the same file. All conversation history lives in the note itself using %% comment markers, so nothing leaves your vault.

• 21 built-in tools -- The AI can search your vault, read/create/edit notes, browse the web, search academic papers, query Wikipedia, fetch Chinese news, and more. Tools are called automatically when needed.

• Thinking mode -- DeepSeek's reasoning/thinking is captured and displayed in collapsible %% comment blocks. Reasoning context is preserved across multi-turn conversations for coherent long interactions.

• Streaming responses -- Responses stream into the note as they are generated. File writes are batched at configurable intervals (20-500ms) for smooth rendering.

• FIM completion -- Fill-in-the-Middle code/text completion via the +++ marker. Place +++ on a line where you want content inserted; everything above it is the prefix, everything below is the suffix. Use +++512 to set a custom max token count.

• NOTEBRAIN.md -- A vault-wide AI instruction file, auto-created on first load. Describe your vault structure, note conventions, and preferences. The contents are injected into the AI's system prompt with highest priority.

• Chat cache -- 30-minute in-memory cache preserves tool call history and thinking context between messages, so the AI maintains full conversational awareness even when you switch notes and come back.

• Tool permissions -- Destructive tools (createNote, editNote) require user approval via a modal dialog before execution. Notes must carry a configurable permission tag (default #notebrain) to be editable.

• Mobile compatible -- Works on both desktop and mobile. Uses Obsidian's requestUrl() for CSP compliance and vanilla DOM only (no React).

Quick Start

1. Install the plugin and enable it in Obsidian's Community Plugins settings.
2. Go to Settings > Notebrain > Model and enter your DeepSeek API key (from platform.deepseek.com).
3. Open any note and press Ctrl+Shift+Enter (or Cmd+Shift+Enter on macOS).
4. Type your message and watch the AI respond directly in the note.

The first load creates a NOTEBRAIN.md file in your vault root. Edit it to tell the AI about your vault structure and preferences.

How to Use

Inline Chat

1. Open any markdown note in edit mode.
2. Press Ctrl+Shift+Enter (or click the brain icon in the ribbon).
3. Type your message at the cursor position.
4. The AI streams its response into the note below your message.

Each conversation turn is structured as:

user message

%%
user
[Timestamp: 2026-05-19T10:30:00.000Z]
%%
---
%%thinking content%%
[Tool calls]
searchNotes: {"query":"project notes"}
%%
AI response here...

%%
assistant
[Timestamp: 2026-05-19T10:30:15.000Z]
%%
---

Thinking blocks and tool calls live inside %%...%% comment pairs (invisible in reading mode). Tool results are passed to the AI but never written to the note. The #notebrain-session tag is automatically added to the note's frontmatter after the first chat session.

FIM Completion

Use Fill-in-the-Middle to generate content between existing text:

Chapter 1: The Beginning

It was a dark and stormy night.
+++
Chapter 2: The Return

Place the cursor on the +++ line and trigger FIM from the ribbon icon (pen) or the Notebrain: FIM Completion command. The AI fills in the gap and replaces the marker with generated content.

To control output length, append a number to the marker:

+++512

FIM uses separate API settings (key, base URL, model) configurable in the FIM settings tab, so you can use a different model than the chat model.

NOTEBRAIN.md

The NOTEBRAIN.md file is the instruction manual for the AI in your vault. It is auto-created with a template on first load. The AI treats these instructions with highest priority.

Example NOTEBRAIN.md:

---
tags:
  - notebrain
---

# NOTEBRAIN.md

## Vault Structure
- Daily/ -- daily notes, named YYYY-MM-DD
- Projects/ -- project plans and tracking
- Reference/ -- knowledge base and research

## Note Conventions
- All notes use "date" and "tags" in frontmatter
- Meeting notes start with "Meeting -"
- Use [[wikilinks]] for all internal references

## Preferences
- Language: Chinese
- Response style: Concise
- Never create notes without confirmation

The file path is configurable in Settings > Notebrain > Basic. The plugin searches for any markdown file named "notebrain" in your vault and loads the first one it finds with the permission tag.

Settings

Basic

Setting	Description	Default
Language	UI language (Chinese / English)	zh
NOTEBRAIN.md path	Path to your vault instruction file	NOTEBRAIN.md
Write frequency	File write interval in milliseconds during streaming (20-500)	80

Model

Setting	Description	Default
API key	DeepSeek API key (sk-...)	--
Base URL	API endpoint URL	https://api.deepseek.com
Model	Model name (dynamic list fetched from API)	deepseek-v4-pro
Thinking mode	Enable DeepSeek reasoning/thinking	On
Reasoning effort	Reasoning depth (high or max)	high
Temperature	Sampling temperature (0-2, only when thinking is off)	0.7

Tools

Setting	Description	Default
Tavily API key	For Tavily search/extract/crawl tools (tvly-...)	--
GitHub token	For higher GitHub API rate limits (ghp_...)	--
Baidu API key	For Baidu Baike encyclopedia (bce-...)	--
Headless browser endpoint	Custom endpoint for JS-rendered page fetching	--
Per-tool toggles	Enable/disable individual tools	All on

Note

Setting	Description	Default
YAML frontmatter	Whether createNote adds YAML frontmatter	On
Edit permission tag	Tag required on notes for editNote to modify them	#notebrain
Note template	Template note for createNote (select from vault)	--

FIM

FIM (Fill-in-the-Middle) uses separate API credentials from the chat model, so you can use a different provider or model.

Setting	Description	Default
API key	FIM API key (sk-...)	--
Base URL	FIM API endpoint	https://api.deepseek.com
Model	FIM model name	deepseek-v4-pro
Temperature	Sampling temperature (0-2)	1.0
Max tokens	Default max output tokens (1-4096)	1024

Tools Reference

Vault (6)

Tool	Description	Requires
searchNotes	Full-text search with keyword, tag, filename, path, property, and regex support. Operators: OR, -exclude, "exact phrase"	--
readNote	Read note content by name (wikilink-style) or vault-relative path. Supports offset/limit for large files	--
listFolder	List files and folders in a vault directory	--
getBacklinks	Get all notes that link to a specific note	--
createNote	Create a new note at a specified path. Uses configurable template. Shows approval modal	--
editNote	Edit an existing note (append, prepend, replace, or find-replace). Requires permission tag. Shows approval modal	#notebrain tag on note

Time (1)

Tool	Description	Requires
getCurrentTime	Get current date/time in multiple formats (ISO, Unix, locale)	--

Web -- Free (3)

Tool	Description	Requires
webSearch	Free web search using Baidu and Bing simultaneously. Requires 3+ keywords for best results	--
webFetch	Fetch and extract clean content from any URL. Uses Jina AI for rendering or optional headless browser endpoint	--
cnNews	Fetch headlines and article summaries from 23 major Chinese news sites (Xinhua, People's Daily, CCTV, NetEase, Sina, etc.)	--

Tavily (6)

All Tavily tools require a Tavily API key (free tier available at tavily.com).

Tool	Description	Requires
tavilySearch	AI-curated web search with titles, URLs, snippets, and relevance scores	Tavily API key
tavilyExtract	Extract clean markdown/text content from up to 20 URLs. Strips navigation, ads, and clutter	Tavily API key
tavilyCrawl	Deep crawl starting from a URL with configurable depth and breadth. Good for documentation sites	Tavily API key
tavilyMap	Map a website's structure -- returns a list of URLs found starting from a base URL	Tavily API key
tavilyResearch	Comprehensive multi-source research on a topic. Returns a detailed synthesized response	Tavily API key
tavilyResearchGet	Retrieve the results of a previously started Tavily research task	Tavily API key

Academic / Knowledge (4)

Tool	Description	Requires
githubSearch	Search GitHub repositories, code, issues, users, commits, topics, and labels with full qualifier support	GitHub token (optional, for higher rate limits)
arxivSearch	Search arXiv preprints. Supports fielded search like cat:cs.AI, ti:transformer, au:name	-- (3s rate limit)
arxivDownload	Download arXiv paper PDF and save to vault. Auto-creates a source note with metadata	-- (3s rate limit)
wikipedia	Search Wikipedia or get full article content. Supports 300+ languages	--

Reference (1)

Tool	Description	Requires
baiduBaike	Query Baidu Baike (Baidu Encyclopedia) for Chinese-language encyclopedic articles	Baidu API key (optional)

Installation

From Community Plugins

1. Open Obsidian and go to Settings > Community Plugins.
2. Click Browse and search for "Notebrain".
3. Click Install, then Enable.

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create a folder notebrain inside your vault's .obsidian/plugins/ directory.
3. Copy the three files into the notebrain folder.
4. Restart Obsidian and enable the plugin in Settings > Community Plugins.

BRAT (Beta Testing)

1. Install the BRAT plugin.
2. In BRAT settings, click Add Beta Plugin.
3. Enter the repository URL: https://github.com/kiluahh/notebrain
4. Enable Notebrain in Settings > Community Plugins.

Commands

Command	Default Hotkey	Description
Chat with Notebrain	Ctrl+Shift+Enter / Cmd+Shift+Enter	Start or continue an inline chat in the current note
Chat with Notebrain (no editor)	--	Start chat from the command palette without an open editor
FIM Completion	--	Trigger Fill-in-the-Middle completion at the +++ marker

Ribbon Icons

• Brain icon -- Start inline chat in the active note.
• Pen icon -- Trigger FIM completion at the current cursor position.

Requirements

• Obsidian 1.7.0 or later
• DeepSeek API key (from platform.deepseek.com)
• Optional: Tavily API key for advanced web search
• Optional: GitHub token for higher API rate limits
• Optional: Baidu AppBuilder key for Baidu Baike

Compatibility

• Desktop -- Windows, macOS, Linux
• Mobile -- Android, iOS (vanilla DOM, no React, requestUrl() for CSP compliance)

License

MIT