Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
fix(llm): let set_attribute add same-name labels (closes #12078)
Elian Doran8a1831946a42
diff --git a/apps/server/src/assets/help/help_content.json b/apps/server/src/assets/help/help_content.jsonindex c5d7fa80ed..286be6d2d7 100644--- a/apps/server/src/assets/help/help_content.json+++ b/apps/server/src/assets/help/help_content.json@@ -242,7 +242,7 @@"_help_HAIOFBoYIIdO": "<p>Nightly releases are versions built every day, containing the latest improvements and bugfixes, directly from the main development branch. These versions are generally useful in preparation for a release, to ensure that there are no significant bugs that need to be addressed first, or they can be used to confirm whether a particular bug is fixed or feature is well implemented.</p><h2>Regarding the stability</h2><p>Despite being on a development branch, generally the main branch is pretty stable since PRs are tested before they are merged. If you notice any issues, feel free to report them either via a ticket or via the Matrix.</p><h2>Downloading the nightly release manually</h2><p>Go to <a href=\"https://github.com/TriliumNext/Trilium/releases/tag/nightly\">github.com/TriliumNext/Trilium/releases/tag/nightly</a> and look for the artifacts starting with <code>TriliumNotes-main</code>. Choose the appropriate one for your platform (e.g. <code>windows-x64.zip</code>).</p><p>Depending on your use case, you can either test the portable version or even use the installer.</p><aside class=\"admonition note\"><p>If you choose the installable version (e.g. the .exe on Windows), it will replace your stable installation.</p></aside><aside class=\"admonition important\"><p>By default, the nightly uses the same database as the production version. Generally you could easily downgrade if needed. However, if there are changes to the database or sync version, it will not be possible to downgrade without having to restore from a backup.</p></aside><h2>Automatically download and install the latest nightly</h2><p>This is pretty useful if you are a beta tester that wants to periodically update their version:</p><div class=\"trilium-tabs\"><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bxl-tux\"></span> Ubuntu (Bash)</p><div class=\"trilium-tab-panel\"><pre><code class=\"language-text-x-sh\">#!/usr/bin/env bash\n\nname=TriliumNotes-linux-x64-nightly.deb\nrm -f $name*\nwget https://github.com/TriliumNext/Trilium/releases/download/nightly/$name\nsudo apt-get install ./$name\nrm $name</code></pre></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bxl-windows\"></span> Windows (PowerShell)</p><div class=\"trilium-tab-panel\"><pre><code class=\"language-application-x-powershell\">if ($env:PROCESSOR_ARCHITECTURE -eq \"ARM64\") {\n $arch = \"arm64\";\n} else {\n $arch = \"x64\";\n}\n\n$exeUrl = \"https://github.com/TriliumNext/Trilium/releases/download/nightly/TriliumNotes-main-windows-$($arch).exe\";\nWrite-Host \"Downloading $($exeUrl)\"\n\n# Generate a unique path in the temp dir\n$guid = [guid]::NewGuid().ToString()\n$destination = Join-Path -Path $env:TEMP -ChildPath \"$guid.exe\"\n\ntry {\n $ProgressPreference = 'SilentlyContinue'\n Invoke-WebRequest -Uri $exeUrl -OutFile $destination\n $process = Start-Process -FilePath $destination\n} catch {\n Write-Error \"An error occurred: $_\"\n} finally {\n # Clean up\n if (Test-Path $destination) {\n Remove-Item -Path $destination -Force\n }\n}</code></pre></div></section></div>","_help_ZmT9ln8XJX2o": "<aside class=\"admonition warning\"><p>This functionality is still in preview, expect possible issues or even the feature disappearing completely.<br>Feel free to <a href=\"#root/_help_wy8So3yZZlH9\">report</a> any issues you might have.</p></aside><p>The read-only database is an alternative to <a class=\"reference-link\" href=\"#root/_help_R9pX4DGra2Vt\">Sharing</a> notes. Although the share functionality works pretty well to publish pages to the Internet in a wiki, blog-like format it does not offer the full functionality behind Trilium (such as the advanced <a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a> or the interactivity behind <a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a> or the various <a class=\"reference-link\" href=\"#root/_help_KSZ04uQ2D1St\">Note Types</a>).</p><p>When the database is in read-only mode, the Trilium application can be used as normal, but editing is disabled and changes are made in-memory only.</p><h2>What it does</h2><ul><li>All notes are read-only, without the possibility of editing them.</li><li>Features that would normally alter the database such as the list of recent notes are disabled.</li></ul><h2>Limitations</h2><ul><li>Some features might “slip through” and still end up creating a note, for example.<ul><li>However, the database is still read-only, so all modifications will be reset if the server is restarted.</li><li>Whenever this occurs, <code>ERROR: read-only DB ignored</code> will be shown in the logs.</li></ul></li></ul><h2>Setting a database as read-only</h2><p>First, make sure the database is initialized (e.g. the first set up is complete). Then modify the <a href=\"#root/_help_Gzjqa934BdH4\">config.ini</a> by looking for the <code>[General]</code> section and adding a new <code>readOnly</code> field:</p><pre><code class=\"language-text-x-trilium-auto\">[General]\nreadOnly=true</code></pre><p>If your server is already running, restart it to apply the changes.</p><p>Similarly, to disable read-only remove the line or set it to <code>false</code>.</p>","_help_TiQbQDgP8L5t": "<p>Optical Character Recognition is the process in which the text from images or PDFs is extracted.</p><h2>Built-in support</h2><p>Since v0.103.0, Trilium has built-in support for OCR. The extracted text can be:</p><ul><li>Integrated with <a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a>, to quickly find the image or file based on snippets of text.</li><li>Integrated with the <a class=\"reference-link\" href=\"#root/_help_GBBMSlVSOIGP\">AI</a> feature, which allows the agent to access the content of a non-text note.</li><li>Manually accessed for other purposes (e.g. copying into a note or sending it somewhere else).</li></ul><h2>Supported formats</h2><p>OCR in Trilium supports the following formats:</p><h3>Images</h3><ul><li>Both <a href=\"#root/_help_W8vYD3Q1zjCR\">individual image notes</a> and <a href=\"#root/_help_mT0HEkOsz6i1\">attachments in text files</a> are supported.</li><li>Supported formats:<ul><li>JPEG</li><li>PNG</li><li>GIF (only non-animated)</li><li>BMP</li><li>WebP</li></ul></li><li>Note that this feature works best for computer-rendered text rather than handwriting.</li><li>The underlying technology is Tesseract.js.</li></ul><h3>PDFs</h3><p>The PDF extraction supports:</p><ul><li>PDFs with text information (e.g. a PDF created by a browser or a word processing application), in which the text is extracted.</li><li>Scanned PDFs, and other PDFs whose text cannot be selected (such as documents whose text was converted to outlines), in which the text is extracted through an OCR process.</li><li>Mixed PDFs, containing both text and images with text content.</li></ul><p>Note that OCR extraction is limited to 50 pages per PDF, pages containing text information (not as an image) are not subject to this limitation.</p><aside class=\"admonition note\"><p>Text extraction for scanned PDFs using OCR was introduced in v0.106.0. If a scanned PDF was already processed by an earlier version, reprocess it individually via <em>Process OCR</em>; batch processing only handles files that haven't been OCR'd yet.</p></aside><h3>Office documents</h3><p>The text will be extracted from the following file formats:</p><ul><li>Microsoft Word documents</li><li>Microsoft Excel documents<ul><li>Only the raw text information, the cell structure is not maintained.</li><li>Values are extracted raw, so searching for dates will not work. The OpenDocument alternative will actually extract the properly formatted value.</li></ul></li><li>Microsoft PowerPoint documents</li><li>The OpenDocument alternatives to the previous formats (Text, Spreadsheet, Presentation), created by editors such as LibreOffice and OpenOffice.</li><li><a href=\"https://en.wikipedia.org/wiki/Rich_Text_Format\">Rich Text Format (RTF)</a>, since v0.104.0.</li><li><a href=\"https://en.wikipedia.org/wiki/EPUB\">EPUB</a>, since v0.104.1.</li></ul><h2>Configuring and triggering OCR</h2><p>The OCR can be configured by going to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsMedia\">Media</a> and looking for the <em>Text Extraction (OCR)</em> section.</p><p>There are three ways to trigger the OCR:</p><ul><li>By enabling <em>Auto-process new files</em> which will process only the notes or attachments created after enabling the option, existing files will remain unprocessed.</li><li>By pressing <em>Start Batch Processing</em> which will process all the existing notes.</li><li>By manually requesting for an image or file to have its text extracted, regardless of whether the automatic processing is enabled or not.</li></ul><h3>Minimum confidence</h3><p>When extracting text from an image, there is a certain level of confidence which indicates whether the extracted text appears relevant.</p><p>When the minimum confidence is set to a low percentage, the text extraction can interpret symbols and drawings incorrectly resulting in garbled text.</p><p>If the extracted text for a note or an attachment quality is lower than the minimum confidence, the OCR is disregarded.</p><h2>Language management</h2><p>OCR needs to be aware of the language of the content in order for it to work correctly. The reason is that each language has its own data which needs to be downloaded, and accents or other symbols will not be supported by the default language.</p><p>To configure the languages that are supported by the OCR, simply go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsLocalization\">Language & Region</a> and adjust the <em>Content languages</em>.</p><p>When there are no content languages defined, the user interface <em>Language</em> is used instead.</p><p>After making this change, the automatic processing or manual reprocessing will take into consideration the new languages.</p><p>To enforce the detection in a particular language for a given note, use the <code>language</code> <a href=\"#root/_help_zEY4DaJG4YT5\">attribute</a>, similar to <a href=\"#root/_help_veGu4faJErEM\">text content language</a>. For <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a>, it's not possible to manually adjust the language.</p><aside class=\"admonition note\"><p>The trained data for each language is not packaged with Trilium, as that would require a significant amount of space that might not be otherwise needed. As such, when the trained data will be downloaded automatically via <a href=\"https://github.com/naptha/tesseract.js/\">Tesseract.js</a>.</p><p>The downloaded trained data is located in the <a class=\"reference-link\" href=\"#root/_help_tAassRL4RSQL\">Data directory</a>, in the <code>ocr-cache</code> directory.</p></aside><h2>Viewing extracted content for a single note</h2><p>To access the extracted content of a note:</p><ul><li>For <a class=\"reference-link\" href=\"#root/_help_W8vYD3Q1zjCR\">File</a> notes, go to the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> → <em>Advanced</em> → <em>View OCR Text</em>.</li><li>For <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a> (e.g. <a class=\"reference-link\" href=\"#root/_help_mT0HEkOsz6i1\">Images</a> in <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes), double-click the attachment to view the details, press the […] button at the left and select <em>View extracted text (OCR)</em>.</li></ul><p>This section allows:</p><ul><li>Viewing the extracted text, which can be copied elsewhere if needed or just to check the quality of the extraction.</li><li>If the note has not been extracted yet, pressing <em>Process OCR</em> will process it in the background. If the extraction confidence is lower than the minimum confidence, there will be a notification.</li><li>Similarly, if the minimum confidence was changed in settings, it is possible to press the <em>Process OCR</em> button again to extract the text again.</li></ul>",- "_help_GBBMSlVSOIGP": "<p>Trilium can connect to a large language model and use it as an assistant that works directly on your notes: ask questions about the note you're reading, have it draft or restructure content, or get it to write scripts and widgets for you.</p><p>The integration is off by default and does nothing until you enable it and configure a provider; Trilium ships no model of its own. The provider you pick decides how your notes travel: a cloud API billed per use, a subscription you already pay for, or a model running on your own hardware, in which case nothing leaves the machine. See <a class=\"reference-link\" href=\"#root/_help_bkPZAMT7d2sR\">Providers</a> for what each involves, and <a class=\"reference-link\" href=\"#root/_help_cRRrdZjgyhNc\">Privacy</a> for exactly what gets sent.</p><p>Once enabled, the assistant is available as:</p><ul><li>As a dedicated note type, it can read and modify notes through tools, which you can switch off per conversation if you would rather it only saw what you type.</li><li>A panel in the right sidebar, which acts similarly to the dedicated note type but it also has optional access to the current note.</li><li>An <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a> which comes with builtin actions that operate over selected text (such as proof-reading, summarizing), as well as <a class=\"reference-link\" href=\"#root/_help_mVEYwt20exhO\">Custom AI quick actions</a>.</li></ul><h2>Feature highlights</h2><ul><li>Chat-based interface with live streaming of the messages.</li><li>Provides the AI context with the note currently being looked at.</li><li>Tools to alter note content, create new notes, etc.</li><li>Statistics regarding context window use and pricing per message.</li><li>Attachments for multi-modal chat (images, text files, PDFs).</li><li>Optional MCP to allow external chat tools (e.g. Claude Code) to operate on notes within Trilium.</li></ul><h2>Sample use-cases</h2><ul><li>Create any type of <a class=\"reference-link\" href=\"#root/_help_MgibgPcfeuGz\">Custom Widgets</a>.</li><li>Easily create a <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>, e.g. <em>Create for me a render note which allows me to play tic-tac-toe. Make sure to use Preact instead of the legacy jQuery.</em></li><li>Create widgets for a <a class=\"reference-link\" href=\"#root/_help_IF7Q6I9x7zuw\">Dashboard</a>, such as a calculator, a stopwatch, a pomodoro timer.</li></ul><aside class=\"admonition note\"><p>Claude Sonnet is known to produce very good frontend or backend scripts with little guidance, as the AI has been instructed in how to produce them.</p></aside><h2>LLM Providers</h2><p>Trilium supports four different types of providers:</p><div class=\"trilium-tabs\"><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-cloud\"></span> Cloud</p><div class=\"trilium-tab-panel\"><p>Pay-per use with an API key which is billed separately from any subscription you might already have.</p><ul><li><span class=\"tn-icon tn-brand tn-brand-anthropic\"></span> Anthropic Claude</li><li><span class=\"tn-icon tn-brand tn-brand-openai\"></span> OpenAI GPT</li><li><span class=\"tn-icon tn-brand tn-brand-gemini\"></span> Google Gemini</li><li><span class=\"tn-icon tn-brand tn-brand-deepseek\"></span> DeepSeek</li><li><span class=\"tn-icon tn-brand tn-brand-openrouter\"></span> OpenRouter, which reaches the models of most labs with one key</li></ul></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-coin\"></span> Subscription-based</p><div class=\"trilium-tab-panel\"><p>Reuses an existing subscription instead of paying per use.</p><ul><li><span class=\"tn-icon tn-brand tn-brand-claude\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">Claude Code</a></li><li><span class=\"tn-icon tn-brand tn-brand-github-copilot\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">GitHub Copilot</a></li><li><span class=\"tn-icon tn-brand tn-brand-antigravity\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">Google Antigravity</a></li><li><span class=\"tn-icon tn-brand tn-brand-codex\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">OpenAI Codex</a></li></ul></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-network-chart\"></span> Local/self-hosted</p><div class=\"trilium-tab-panel\"><ul><li><span class=\"tn-icon tn-brand tn-brand-ollama\"></span> Ollama</li><li><span class=\"tn-icon tn-brand tn-brand-lmstudio\"></span> LM Studio</li></ul></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-code-curly\"></span> Custom endpoints</p><div class=\"trilium-tab-panel\"><p>For other providers that are not directly supported by Trilium, either local or hosted (e.g. Groq, Mistral, Together).</p></div></section></div><aside class=\"admonition tip\"><p>For more information about each provider, see <a class=\"reference-link\" href=\"#root/_help_bkPZAMT7d2sR\">Providers</a>. See the dedicated <a class=\"reference-link\" href=\"#root/_help_cRRrdZjgyhNc\">Privacy</a> to better understand what data is sent to providers.</p></aside><h2>Enabling the AI integration</h2><p>To enable the AI integration, simply go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em> and press the toggle in the top-right of the dialog and configure a provider.</p><h2>Creating a new chat</h2><p>There are two different chat interfaces:</p><ul><li>One in the sidebar.</li><li>A dedicated note type.</li></ul><h3>The sidebar interface</h3><h3>The dedicated note type</h3><p>The dedicated chat note is similar to the sidebar interface, but it makes longer conversations more comfortable to read.</p><p>Unlike the sidebar, the AI will not be aware of the current note it's in.</p><h3>Templates</h3><p>Chat notes can be set as <a class=\"reference-link\" href=\"#root/_help_KC1HB96bqqHX\">Templates</a> to make them easily reusable. The entire conversation history is kept, allowing a basic form of specialization for the LLM with the existing chat acting like a system prompt. </p><h3>Model selection</h3><p>When a provider is configured in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>, the next step is to select the models that will be available for the chat.</p><p>The models are retrieved dynamically from the provider, only when the model selection list is visible. To alter the list of models, simply press the Edit button in the model selection box.</p><p>Pricing information is displayed for known models. The pricing information (price per million tokens) is embedded in the application (using a subset of LiteLLM's data) and is updated with new versions of Trilium. Local providers are considered free, whereas custom endpoint providers don't offer any pricing information.</p><h2>Features</h2><h3>Web search</h3><p>The AI can optionally search the web to find more information about a specific topic. </p><p>Where the search comes from is chosen in the <em>Web search</em> submenu of the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> menu next to the model selector at the bottom of the chat, whose row shows the source in use:</p><ul><li><em>Disabled</em> turns web search off for this chat.</li><li><em>Use the model's built-in search</em>, the default, lets the model search with its provider's own search. Anthropic, OpenAI, Google Gemini and DeepSeek models have one, as do Claude Code, Google Antigravity and OpenAI Codex. OpenRouter, Ollama, LM Studio and custom endpoints don't, so this choice is disabled for their models. DeepSeek's search is billed per search on your DeepSeek account and works only with DeepSeek's own endpoint, not with a custom base URL.</li><li>A search provider (Brave Search, Tavily, Exa, Serper, Perplexity or SearXNG) searches through that service instead, whichever model is answering. Search providers are added in the <em>Search Providers</em> section of the AI settings, which <em>Manage search providers</em> at the bottom of the submenu opens. The browser version can't use Brave Search, Exa or Perplexity, whose services refuse requests made from a web page, so they're shown disabled there.</li></ul><p>To use SearXNG, enable its JSON output by adding <code>json</code> to the search formats in the instance's <code>settings.yml</code>. SearXNG turns JSON off by default, and without it every search fails.</p><pre><code class=\"language-text-x-yaml\">search:\n formats:\n - html\n - json</code></pre><p>SearXNG doesn't use API keys, so leave the API key empty. Fill it in only if your instance sits behind a proxy that requires a token; Trilium sends it as a bearer token in the <code>Authorization</code> header.</p><p>Whether web search is on is kept per chat; the search source is shared by all chats. A choice the current model can't use stays in the menu, disabled; hover the <span class=\"tn-icon bx bx-info-circle\"></span>icon next to it to see why. Claude Code, GitHub Copilot, Google Antigravity and OpenAI Codex run their own tools, so they can't use a search provider.</p><p>In the chat, a search run through a search provider shows that provider's logo at the start of its line instead of the <span class=\"tn-icon bx bx-search\"></span>magnifier; hover the logo to see the provider's name.</p><p>With a search provider, the model can also read the pages it finds, or a link you give it, as text: Trilium fetches the page itself and hands the model up to its first 20,000 characters. Addresses on your own machine or network are refused. In the browser version most sites don't allow being read this way, so reading a page there usually fails.</p><h3>Thinking</h3><p>Some models reason before they answer. While the model is thinking, its reasoning is shown in full under a spinner; once it is done, it folds into a collapsible <em>Thought process</em> line above the reply.</p><p>How much a model thinks is set per chat, in one of two ways depending on the model:</p><ul><li>Most models have an <span class=\"tn-icon bx bx-brain\"></span><em>Extended thinking</em> button, next to the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> button.</li><li>Models that offer several levels of reasoning (DeepSeek V4, OpenRouter models that reason, OpenAI Codex, Antigravity) have a <span class=\"tn-icon bx bx-brain\"></span>reasoning effort dropdown next to the model selector instead. <em>None</em>, where offered, turns thinking off; higher levels give better answers to hard questions, but take longer and cost more.</li></ul><aside class=\"admonition note\"><p>The effort dropdown only appears once Trilium knows the model's levels. For a DeepSeek provider set up with an earlier version of Trilium, edit the provider in the model selection box and press <em>Save</em> once.</p></aside><h3>Note access (tools)</h3><p>Tools allow the agentic AI to understand and operate on notes directly within your Trilium instance.</p><p>This feature is on by default. To turn it off, press the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> button next to the model selector at the bottom of the chat and switch off <em>Note access</em>. The <em>Tools</em> button is highlighted while note access or web search is on.</p><p>Here are a few tools that Trilium provides for the LLM:</p><ul><li>At note level:<ul><li>Search for notes</li><li>Get the metadata or content of a note.</li><li>Edit a note<ul><li>There are multiple mechanism for the LLM to edit a note: completely by re-writing it, find/replace of a text sequence or append.</li><li>When re-writing a note, the LLM can also change its type (for example from a text note to a code note) or the language of a code note, rewriting the content to match.</li><li>Whenever the AI makes a change, a <a href=\"#root/_help_vZWERwf8U3nx\">revision</a> is saved to be able to revert any unwanted changes.</li></ul></li><li>Create a new note<ul><li>Asked for a drawing, the LLM can create an SVG image note, or turn an existing note into one. It can write only SVG images, not other formats such as PNG.</li></ul></li><li>Rename or delete a note.</li></ul></li><li>At attribute level:<ul><li>Get the full list of attributes, or a specific attribute.</li><li>Set the value of an attribute.<ul><li>An attribute that runs code, such as <code>#run</code>, <code>#widget</code> or <code>~renderNote</code>, is saved with a <code>disabled:</code> prefix (for example <code>#disabled:widget</code>), the same way a safe import disables it (see <a class=\"reference-link\" href=\"#root/_help_YzMcWlCVeW09\">Active content</a>). If the note already had that attribute enabled, the AI removes it, so none of it runs until you enable the new value. The AI tells you which note it is on; review the code, then enable it with the toggle next to the active content badge beside the note's title or, for a <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>, the <em>Enable render note</em> button in the note.</li></ul></li><li>Delete an attribute.</li></ul></li><li>At tree level:<ul><li>Get the direct children of a note.</li><li>Get the entire subtree of a note.</li><li>Move or clone a note somewhere else.</li></ul></li><li>For <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a>:<ul><li>Get metadata for an attachment.</li><li>Get the content of an attachment.</li></ul></li><li>Skills (see the dedicated section).</li></ul><p>Each tool the AI uses appears in the chat as a single line naming the tool and the note or query it worked on; a renamed note shows its previous title struck through, a deleted note its title struck through, a moved note where it was moved from and to, an attribute the AI read, set or deleted as a pill (struck through once deleted), an attachment by its title, note and size, and a web page the AI read as a link. A line folds open only when there is something to read inline: the notes a search found, the pages a web search found, the icons an icon search found, the type, attributes or start of the content of a note the AI read, all the attributes of a note, the text of an attachment or of a web page, the User Guide pages the AI looked up or its table of contents (both open in the help panel), the children or the whole subtree of a note, what the AI wrote into a note it created, rewrote or added to, the changes of an edit, or the reason a tool failed. A search names on its line the part of the tree it is confined to, if any, and also shows how many notes it found and how many of the matches the AI asked for; each note it lists opens with a click. To see exactly what the AI sent to a tool and what it got back, hover the line and press the <span class=\"tn-icon bx bx-code-alt\"></span>button next to it; on touch screens the button is always shown.</p><p>When the reply stops moving for a couple of seconds while the AI is still at work, for example while it reads what a tool returned, a <em>Still working…</em> line appears under it until the next part of the reply arrives.</p><h4>Approving tool calls</h4><p>Before the AI runs a tool, the chat asks whether to allow it. The tool's line is marked with a <span class=\"tn-icon bx bxs-hand\"></span>icon and has <em>Allow</em> and <em>Deny</em> buttons below it. When the call would write to a note, the line opens on the text it would write or the changes of an edit. The reply waits until you answer.</p><ul><li>To let the call run, press <em>Allow</em>.</li><li>To stop asking about a tool for the rest of the chat, open the menu next to <em>Allow</em> and choose to always allow that tool for this chat. The call runs, and so do the other calls of that tool still waiting and every later one in this chat. Other tools keep asking, and a new chat asks again.</li><li>To refuse it, press <em>Deny</em>. The AI is told that you declined, and its reply carries on without the call, which is marked <em>denied</em>.</li><li>Stopping the reply denies every call that is still waiting.</li></ul><p>To make a chat ask about a tool again, open the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> menu at the bottom of the chat and, under <em>Allowed in this chat</em>, press the tool. The submenu is shown once the chat has allowed a tool.</p><p>Which calls ask depends on the chat's permission mode, chosen in the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> menu under <em>Permissions</em>:</p><ul><li><em>Always ask</em>: every call asks, including the ones that only read (searching notes, or reading a note or an attachment).</li><li><em>Ask before changes</em>: the calls that only read run on their own, and the ones that change your notes (creating, editing, renaming, moving or deleting a note, and setting or deleting an attribute) ask.</li><li><em>Don't ask</em>: every call runs without asking, changes included.</li></ul><p>A new chat starts in the mode you picked last, in any chat, or in <em>Ask before changes</em> until you pick one. Picking <em>Don't ask</em> therefore carries over to the next chat too.</p><p>A tool allowed for the chat runs without asking in every mode. So does looking something up in what ships with Trilium (its User Guide, the skill sheets that teach the AI Trilium's search syntax and note types, and the icons), since it reads none of your notes. Searching the web and reading a web page never ask either: turning on web search in the <em>Tools</em> menu is what allows them, whether the model searches on its own or through a search provider.</p><aside class=\"admonition note\"><p>The <a class=\"reference-link\" href=\"#root/_help_eFhxp9laTW1S\">Subscription-based providers</a> (Claude Code, GitHub Copilot, Google Antigravity and OpenAI Codex) ask like any other provider.</p></aside><aside class=\"admonition note\"><p>Most changes you allow can be undone: a deleted note can be restored, and an edit reverted from its revision. Setting an attribute is harder to undo, since attributes have no history.</p></aside><aside class=\"admonition note\"><p>Gemini can't use its built-in search while note access is on. While it is, the built-in search choice in the <em>Tools</em> menu is disabled and says why; a search provider works with note access on.</p></aside><h3>Attachments</h3><p>Since Trilium v0.140.0, <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a> allow for multi-modal chat:</p><ul><li>Raster image (sent as vision input, except for SVGs) with the following supported formats: PNG, JPEG, GIF, WebP.</li><li>PDFs, sent natively to the provider (supported by Anthropic, OpenAI and Google).</li><li>SVG images (sent as raw HTML).</li><li>Text files.</li></ul><p>Not every model reads every kind of attachment: DeepSeek reads no PDFs, and images only with its vision models; OpenAI Codex, GitHub Copilot and Google Antigravity read images but no PDFs. For such a model:</p><ul><li>The attach button offers only the kinds the model reads, and a pasted or dropped file it can't read is not attached.</li><li>After switching to such a model, an attachment it can't read is marked with a <span class=\"tn-icon bx bx-error\"></span>warning, and the message can't be sent until the attachment is removed or another model is selected.</li><li>An attachment sent in an earlier message reaches the model as its name only, such as <code>[attached file: report.pdf]</code>, so it can tell you it doesn't see the content.</li></ul><p>To upload an attachment:</p><ul><li>Press the dedicated <em>Attach</em> button (paperclip icon) underneath the text box.</li><li>Paste an image directly from clipboard using Ctrl+V.</li></ul><p>Once one or more attachments are uploaded, they will appear directly above the text box:</p><ul><li>Images have a small thumbnail for easy identifications.</li><li>Every attachment can be deleted by pressing their corresponding X button.</li></ul><p>Clicking an image or a PDF, either its chip above the text box or where it appears in a sent message, opens it in a viewer: an image can be zoomed and panned there, a PDF read page by page. The button next to the viewer's close button opens the original file in a new browser tab. <kbd>Ctrl</kbd>-clicking instead opens an image in a new browser tab, and a PDF as an attachment in a new Trilium tab.</p><p>When an attachment is present, the LLM is instructed to consider the attachment with priority, even if it has access to the current note.</p><aside class=\"admonition note\"><p>Currently Trilium doesn't pre-process the attachments (e.g. via <a class=\"reference-link\" href=\"#root/_help_TiQbQDgP8L5t\">Text Extraction (OCR)</a>) before sending them to the LLM provider.</p></aside><h3>Mentions</h3><p>Mentions are a way to insert references to notes other than the current note, using the same mechanism as <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a>. To refer to another note, simply type @ followed by the name of the note to reference.</p><p>This feature is mostly helpful when note tools are enabled, otherwise the LLM will have no way to access the given note.</p><h3>Skills</h3><p>Skills in Trilium are specialized instruction sets that help the AI be more productive by understanding how Trilium.</p><p>These skills are not loaded by default to avoid an increased consumption of tokens, but the AI can load them on-demand if <em>Note tools</em> are enabled.</p><p>The following skills are built-in:</p><ul><li>Search syntax: understands the full syntax of <a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a>.</li><li>Backend scripting: to be able to write proper <a class=\"reference-link\" href=\"#root/_help_SPirpZypehBG\">Backend scripts</a>.</li><li>Frontend scripting: to be able to write proper <a href=\"#root/_help_yIhgI5H7A2Sm\">front-end scripts</a> (basic scripts, widgets, <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>).</li><li>Dashboards: to build a <a class=\"reference-link\" href=\"#root/_help_IF7Q6I9x7zuw\">Dashboard</a> and its widgets, including interactive ones made with a <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>.</li></ul><p>When <em>Note tools</em> are enabled the skills will automatically be made available to the AI, so no user interaction is required.</p><aside class=\"admonition note\"><p>Custom skills are currently not supported but they are planned.</p></aside><h3>MCP</h3><p>Trilium comes with a built-in MCP server which allows you to use an external agent such as Claude Code have access to your database. See the dedicated <a class=\"reference-link\" href=\"#root/_help_KOWBFgsZXJAD\">MCP</a> page for more details.</p><h2>History</h2><h3>Removal in v0.102.0</h3><p>Starting with version v0.102.0, AI/LLM integration has been removed from the Trilium Notes core.</p><p>While a significant amount of effort went into developing this feature, maintaining and supporting it long-term proved to be unsustainable.</p><p>When upgrading to v0.102.0, your Chat notes will be preserved, but instead of the dedicated chat window they will be turned to a normal <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> note, revealing the underlying JSON of the conversation.</p><h3>Reintroduction in v0.103.0</h3><p>Given the recent advancements of the AI scene, we decided to give the LLM integration another try. v0.103.0 introduces a completely new chat system.</p><p>One of the key changes that lead to the reimplementation is that now we are using a library (<a href=\"https://github.com/vercel/ai\">Vercel AI</a>) to manage the inner mechanism and the differences between LLM providers instead of having to implement it on our own.</p>",+ "_help_GBBMSlVSOIGP": "<p>Trilium can connect to a large language model and use it as an assistant that works directly on your notes: ask questions about the note you're reading, have it draft or restructure content, or get it to write scripts and widgets for you.</p><p>The integration is off by default and does nothing until you enable it and configure a provider; Trilium ships no model of its own. The provider you pick decides how your notes travel: a cloud API billed per use, a subscription you already pay for, or a model running on your own hardware, in which case nothing leaves the machine. See <a class=\"reference-link\" href=\"#root/_help_bkPZAMT7d2sR\">Providers</a> for what each involves, and <a class=\"reference-link\" href=\"#root/_help_cRRrdZjgyhNc\">Privacy</a> for exactly what gets sent.</p><p>Once enabled, the assistant is available as:</p><ul><li>As a dedicated note type, it can read and modify notes through tools, which you can switch off per conversation if you would rather it only saw what you type.</li><li>A panel in the right sidebar, which acts similarly to the dedicated note type but it also has optional access to the current note.</li><li>An <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a> which comes with builtin actions that operate over selected text (such as proof-reading, summarizing), as well as <a class=\"reference-link\" href=\"#root/_help_mVEYwt20exhO\">Custom AI quick actions</a>.</li></ul><h2>Feature highlights</h2><ul><li>Chat-based interface with live streaming of the messages.</li><li>Provides the AI context with the note currently being looked at.</li><li>Tools to alter note content, create new notes, etc.</li><li>Statistics regarding context window use and pricing per message.</li><li>Attachments for multi-modal chat (images, text files, PDFs).</li><li>Optional MCP to allow external chat tools (e.g. Claude Code) to operate on notes within Trilium.</li></ul><h2>Sample use-cases</h2><ul><li>Create any type of <a class=\"reference-link\" href=\"#root/_help_MgibgPcfeuGz\">Custom Widgets</a>.</li><li>Easily create a <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>, e.g. <em>Create for me a render note which allows me to play tic-tac-toe. Make sure to use Preact instead of the legacy jQuery.</em></li><li>Create widgets for a <a class=\"reference-link\" href=\"#root/_help_IF7Q6I9x7zuw\">Dashboard</a>, such as a calculator, a stopwatch, a pomodoro timer.</li></ul><aside class=\"admonition note\"><p>Claude Sonnet is known to produce very good frontend or backend scripts with little guidance, as the AI has been instructed in how to produce them.</p></aside><h2>LLM Providers</h2><p>Trilium supports four different types of providers:</p><div class=\"trilium-tabs\"><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-cloud\"></span> Cloud</p><div class=\"trilium-tab-panel\"><p>Pay-per use with an API key which is billed separately from any subscription you might already have.</p><ul><li><span class=\"tn-icon tn-brand tn-brand-anthropic\"></span> Anthropic Claude</li><li><span class=\"tn-icon tn-brand tn-brand-openai\"></span> OpenAI GPT</li><li><span class=\"tn-icon tn-brand tn-brand-gemini\"></span> Google Gemini</li><li><span class=\"tn-icon tn-brand tn-brand-deepseek\"></span> DeepSeek</li><li><span class=\"tn-icon tn-brand tn-brand-openrouter\"></span> OpenRouter, which reaches the models of most labs with one key</li></ul></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-coin\"></span> Subscription-based</p><div class=\"trilium-tab-panel\"><p>Reuses an existing subscription instead of paying per use.</p><ul><li><span class=\"tn-icon tn-brand tn-brand-claude\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">Claude Code</a></li><li><span class=\"tn-icon tn-brand tn-brand-github-copilot\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">GitHub Copilot</a></li><li><span class=\"tn-icon tn-brand tn-brand-antigravity\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">Google Antigravity</a></li><li><span class=\"tn-icon tn-brand tn-brand-codex\"></span> <a href=\"#root/_help_eFhxp9laTW1S\">OpenAI Codex</a></li></ul></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-network-chart\"></span> Local/self-hosted</p><div class=\"trilium-tab-panel\"><ul><li><span class=\"tn-icon tn-brand tn-brand-ollama\"></span> Ollama</li><li><span class=\"tn-icon tn-brand tn-brand-lmstudio\"></span> LM Studio</li></ul></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-code-curly\"></span> Custom endpoints</p><div class=\"trilium-tab-panel\"><p>For other providers that are not directly supported by Trilium, either local or hosted (e.g. Groq, Mistral, Together).</p></div></section></div><aside class=\"admonition tip\"><p>For more information about each provider, see <a class=\"reference-link\" href=\"#root/_help_bkPZAMT7d2sR\">Providers</a>. See the dedicated <a class=\"reference-link\" href=\"#root/_help_cRRrdZjgyhNc\">Privacy</a> to better understand what data is sent to providers.</p></aside><h2>Enabling the AI integration</h2><p>To enable the AI integration, simply go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em> and press the toggle in the top-right of the dialog and configure a provider.</p><h2>Creating a new chat</h2><p>There are two different chat interfaces:</p><ul><li>One in the sidebar.</li><li>A dedicated note type.</li></ul><h3>The sidebar interface</h3><h3>The dedicated note type</h3><p>The dedicated chat note is similar to the sidebar interface, but it makes longer conversations more comfortable to read.</p><p>Unlike the sidebar, the AI will not be aware of the current note it's in.</p><h3>Templates</h3><p>Chat notes can be set as <a class=\"reference-link\" href=\"#root/_help_KC1HB96bqqHX\">Templates</a> to make them easily reusable. The entire conversation history is kept, allowing a basic form of specialization for the LLM with the existing chat acting like a system prompt. </p><h3>Model selection</h3><p>When a provider is configured in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>, the next step is to select the models that will be available for the chat.</p><p>The models are retrieved dynamically from the provider, only when the model selection list is visible. To alter the list of models, simply press the Edit button in the model selection box.</p><p>Pricing information is displayed for known models. The pricing information (price per million tokens) is embedded in the application (using a subset of LiteLLM's data) and is updated with new versions of Trilium. Local providers are considered free, whereas custom endpoint providers don't offer any pricing information.</p><h2>Features</h2><h3>Web search</h3><p>The AI can optionally search the web to find more information about a specific topic. </p><p>Where the search comes from is chosen in the <em>Web search</em> submenu of the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> menu next to the model selector at the bottom of the chat, whose row shows the source in use:</p><ul><li><em>Disabled</em> turns web search off for this chat.</li><li><em>Use the model's built-in search</em>, the default, lets the model search with its provider's own search. Anthropic, OpenAI, Google Gemini and DeepSeek models have one, as do Claude Code, Google Antigravity and OpenAI Codex. OpenRouter, Ollama, LM Studio and custom endpoints don't, so this choice is disabled for their models. DeepSeek's search is billed per search on your DeepSeek account and works only with DeepSeek's own endpoint, not with a custom base URL.</li><li>A search provider (Brave Search, Tavily, Exa, Serper, Perplexity or SearXNG) searches through that service instead, whichever model is answering. Search providers are added in the <em>Search Providers</em> section of the AI settings, which <em>Manage search providers</em> at the bottom of the submenu opens. The browser version can't use Brave Search, Exa or Perplexity, whose services refuse requests made from a web page, so they're shown disabled there.</li></ul><p>To use SearXNG, enable its JSON output by adding <code>json</code> to the search formats in the instance's <code>settings.yml</code>. SearXNG turns JSON off by default, and without it every search fails.</p><pre><code class=\"language-text-x-yaml\">search:\n formats:\n - html\n - json</code></pre><p>SearXNG doesn't use API keys, so leave the API key empty. Fill it in only if your instance sits behind a proxy that requires a token; Trilium sends it as a bearer token in the <code>Authorization</code> header.</p><p>Whether web search is on is kept per chat; the search source is shared by all chats. A choice the current model can't use stays in the menu, disabled; hover the <span class=\"tn-icon bx bx-info-circle\"></span>icon next to it to see why. Claude Code, GitHub Copilot, Google Antigravity and OpenAI Codex run their own tools, so they can't use a search provider.</p><p>In the chat, a search run through a search provider shows that provider's logo at the start of its line instead of the <span class=\"tn-icon bx bx-search\"></span>magnifier; hover the logo to see the provider's name.</p><p>With a search provider, the model can also read the pages it finds, or a link you give it, as text: Trilium fetches the page itself and hands the model up to its first 20,000 characters. Addresses on your own machine or network are refused. In the browser version most sites don't allow being read this way, so reading a page there usually fails.</p><h3>Thinking</h3><p>Some models reason before they answer. While the model is thinking, its reasoning is shown in full under a spinner; once it is done, it folds into a collapsible <em>Thought process</em> line above the reply.</p><p>How much a model thinks is set per chat, in one of two ways depending on the model:</p><ul><li>Most models have an <span class=\"tn-icon bx bx-brain\"></span><em>Extended thinking</em> button, next to the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> button.</li><li>Models that offer several levels of reasoning (DeepSeek V4, OpenRouter models that reason, OpenAI Codex, Antigravity) have a <span class=\"tn-icon bx bx-brain\"></span>reasoning effort dropdown next to the model selector instead. <em>None</em>, where offered, turns thinking off; higher levels give better answers to hard questions, but take longer and cost more.</li></ul><aside class=\"admonition note\"><p>The effort dropdown only appears once Trilium knows the model's levels. For a DeepSeek provider set up with an earlier version of Trilium, edit the provider in the model selection box and press <em>Save</em> once.</p></aside><h3>Note access (tools)</h3><p>Tools allow the agentic AI to understand and operate on notes directly within your Trilium instance.</p><p>This feature is on by default. To turn it off, press the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> button next to the model selector at the bottom of the chat and switch off <em>Note access</em>. The <em>Tools</em> button is highlighted while note access or web search is on.</p><p>Here are a few tools that Trilium provides for the LLM:</p><ul><li>At note level:<ul><li>Search for notes</li><li>Get the metadata or content of a note.</li><li>Edit a note<ul><li>There are multiple mechanism for the LLM to edit a note: completely by re-writing it, find/replace of a text sequence or append.</li><li>When re-writing a note, the LLM can also change its type (for example from a text note to a code note) or the language of a code note, rewriting the content to match.</li><li>Whenever the AI makes a change, a <a href=\"#root/_help_vZWERwf8U3nx\">revision</a> is saved to be able to revert any unwanted changes.</li></ul></li><li>Create a new note<ul><li>Asked for a drawing, the LLM can create an SVG image note, or turn an existing note into one. It can write only SVG images, not other formats such as PNG.</li></ul></li><li>Rename or delete a note.</li></ul></li><li>At attribute level:<ul><li>Get the full list of attributes, or a specific attribute.</li><li>Set the value of an attribute, or add another value next to the existing ones (such as a second <code>#tag</code>). When setting a value replaces an existing one, the AI is told which value it replaced.<ul><li>An attribute that runs code, such as <code>#run</code>, <code>#widget</code> or <code>~renderNote</code>, is saved with a <code>disabled:</code> prefix (for example <code>#disabled:widget</code>), the same way a safe import disables it (see <a class=\"reference-link\" href=\"#root/_help_YzMcWlCVeW09\">Active content</a>). If the note already had that attribute enabled and the AI sets rather than adds the value, the AI removes the enabled one, so none of it runs until you enable the new value. The AI tells you which note it is on; review the code, then enable it with the toggle next to the active content badge beside the note's title or, for a <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>, the <em>Enable render note</em> button in the note.</li></ul></li><li>Delete an attribute.</li></ul></li><li>At tree level:<ul><li>Get the direct children of a note.</li><li>Get the entire subtree of a note.</li><li>Move or clone a note somewhere else.</li></ul></li><li>For <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a>:<ul><li>Get metadata for an attachment.</li><li>Get the content of an attachment.</li></ul></li><li>Skills (see the dedicated section).</li></ul><p>Each tool the AI uses appears in the chat as a single line naming the tool and the note or query it worked on; a renamed note shows its previous title struck through, a deleted note its title struck through, a moved note where it was moved from and to, an attribute the AI read, set or deleted as a pill (struck through once deleted), an attachment by its title, note and size, and a web page the AI read as a link. A line folds open only when there is something to read inline: the notes a search found, the pages a web search found, the icons an icon search found, the type, attributes or start of the content of a note the AI read, all the attributes of a note, the text of an attachment or of a web page, the User Guide pages the AI looked up or its table of contents (both open in the help panel), the children or the whole subtree of a note, what the AI wrote into a note it created, rewrote or added to, the changes of an edit, or the reason a tool failed. A search names on its line the part of the tree it is confined to, if any, and also shows how many notes it found and how many of the matches the AI asked for; each note it lists opens with a click. To see exactly what the AI sent to a tool and what it got back, hover the line and press the <span class=\"tn-icon bx bx-code-alt\"></span>button next to it; on touch screens the button is always shown.</p><p>When the reply stops moving for a couple of seconds while the AI is still at work, for example while it reads what a tool returned, a <em>Still working…</em> line appears under it until the next part of the reply arrives.</p><h4>Approving tool calls</h4><p>Before the AI runs a tool, the chat asks whether to allow it. The tool's line is marked with a <span class=\"tn-icon bx bxs-hand\"></span>icon and has <em>Allow</em> and <em>Deny</em> buttons below it. When the call would write to a note, the line opens on the text it would write or the changes of an edit. The reply waits until you answer.</p><ul><li>To let the call run, press <em>Allow</em>.</li><li>To stop asking about a tool for the rest of the chat, open the menu next to <em>Allow</em> and choose to always allow that tool for this chat. The call runs, and so do the other calls of that tool still waiting and every later one in this chat. Other tools keep asking, and a new chat asks again.</li><li>To refuse it, press <em>Deny</em>. The AI is told that you declined, and its reply carries on without the call, which is marked <em>denied</em>.</li><li>Stopping the reply denies every call that is still waiting.</li></ul><p>To make a chat ask about a tool again, open the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> menu at the bottom of the chat and, under <em>Allowed in this chat</em>, press the tool. The submenu is shown once the chat has allowed a tool.</p><p>Which calls ask depends on the chat's permission mode, chosen in the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> menu under <em>Permissions</em>:</p><ul><li><em>Always ask</em>: every call asks, including the ones that only read (searching notes, or reading a note or an attachment).</li><li><em>Ask before changes</em>: the calls that only read run on their own, and the ones that change your notes (creating, editing, renaming, moving or deleting a note, and setting or deleting an attribute) ask.</li><li><em>Don't ask</em>: every call runs without asking, changes included.</li></ul><p>A new chat starts in the mode you picked last, in any chat, or in <em>Ask before changes</em> until you pick one. Picking <em>Don't ask</em> therefore carries over to the next chat too.</p><p>A tool allowed for the chat runs without asking in every mode. So does looking something up in what ships with Trilium (its User Guide, the skill sheets that teach the AI Trilium's search syntax and note types, and the icons), since it reads none of your notes. Searching the web and reading a web page never ask either: turning on web search in the <em>Tools</em> menu is what allows them, whether the model searches on its own or through a search provider.</p><aside class=\"admonition note\"><p>The <a class=\"reference-link\" href=\"#root/_help_eFhxp9laTW1S\">Subscription-based providers</a> (Claude Code, GitHub Copilot, Google Antigravity and OpenAI Codex) ask like any other provider.</p></aside><aside class=\"admonition note\"><p>Most changes you allow can be undone: a deleted note can be restored, and an edit reverted from its revision. Setting an attribute is harder to undo, since attributes have no history.</p></aside><aside class=\"admonition note\"><p>Gemini can't use its built-in search while note access is on. While it is, the built-in search choice in the <em>Tools</em> menu is disabled and says why; a search provider works with note access on.</p></aside><h3>Attachments</h3><p>Since Trilium v0.140.0, <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a> allow for multi-modal chat:</p><ul><li>Raster image (sent as vision input, except for SVGs) with the following supported formats: PNG, JPEG, GIF, WebP.</li><li>PDFs, sent natively to the provider (supported by Anthropic, OpenAI and Google).</li><li>SVG images (sent as raw HTML).</li><li>Text files.</li></ul><p>Not every model reads every kind of attachment: DeepSeek reads no PDFs, and images only with its vision models; OpenAI Codex, GitHub Copilot and Google Antigravity read images but no PDFs. For such a model:</p><ul><li>The attach button offers only the kinds the model reads, and a pasted or dropped file it can't read is not attached.</li><li>After switching to such a model, an attachment it can't read is marked with a <span class=\"tn-icon bx bx-error\"></span>warning, and the message can't be sent until the attachment is removed or another model is selected.</li><li>An attachment sent in an earlier message reaches the model as its name only, such as <code>[attached file: report.pdf]</code>, so it can tell you it doesn't see the content.</li></ul><p>To upload an attachment:</p><ul><li>Press the dedicated <em>Attach</em> button (paperclip icon) underneath the text box.</li><li>Paste an image directly from clipboard using Ctrl+V.</li></ul><p>Once one or more attachments are uploaded, they will appear directly above the text box:</p><ul><li>Images have a small thumbnail for easy identifications.</li><li>Every attachment can be deleted by pressing their corresponding X button.</li></ul><p>Clicking an image or a PDF, either its chip above the text box or where it appears in a sent message, opens it in a viewer: an image can be zoomed and panned there, a PDF read page by page. The button next to the viewer's close button opens the original file in a new browser tab. <kbd>Ctrl</kbd>-clicking instead opens an image in a new browser tab, and a PDF as an attachment in a new Trilium tab.</p><p>When an attachment is present, the LLM is instructed to consider the attachment with priority, even if it has access to the current note.</p><aside class=\"admonition note\"><p>Currently Trilium doesn't pre-process the attachments (e.g. via <a class=\"reference-link\" href=\"#root/_help_TiQbQDgP8L5t\">Text Extraction (OCR)</a>) before sending them to the LLM provider.</p></aside><h3>Mentions</h3><p>Mentions are a way to insert references to notes other than the current note, using the same mechanism as <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a>. To refer to another note, simply type @ followed by the name of the note to reference.</p><p>This feature is mostly helpful when note tools are enabled, otherwise the LLM will have no way to access the given note.</p><h3>Skills</h3><p>Skills in Trilium are specialized instruction sets that help the AI be more productive by understanding how Trilium.</p><p>These skills are not loaded by default to avoid an increased consumption of tokens, but the AI can load them on-demand if <em>Note tools</em> are enabled.</p><p>The following skills are built-in:</p><ul><li>Search syntax: understands the full syntax of <a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a>.</li><li>Backend scripting: to be able to write proper <a class=\"reference-link\" href=\"#root/_help_SPirpZypehBG\">Backend scripts</a>.</li><li>Frontend scripting: to be able to write proper <a href=\"#root/_help_yIhgI5H7A2Sm\">front-end scripts</a> (basic scripts, widgets, <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>).</li><li>Dashboards: to build a <a class=\"reference-link\" href=\"#root/_help_IF7Q6I9x7zuw\">Dashboard</a> and its widgets, including interactive ones made with a <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a>.</li></ul><p>When <em>Note tools</em> are enabled the skills will automatically be made available to the AI, so no user interaction is required.</p><aside class=\"admonition note\"><p>Custom skills are currently not supported but they are planned.</p></aside><h3>MCP</h3><p>Trilium comes with a built-in MCP server which allows you to use an external agent such as Claude Code have access to your database. See the dedicated <a class=\"reference-link\" href=\"#root/_help_KOWBFgsZXJAD\">MCP</a> page for more details.</p><h2>History</h2><h3>Removal in v0.102.0</h3><p>Starting with version v0.102.0, AI/LLM integration has been removed from the Trilium Notes core.</p><p>While a significant amount of effort went into developing this feature, maintaining and supporting it long-term proved to be unsustainable.</p><p>When upgrading to v0.102.0, your Chat notes will be preserved, but instead of the dedicated chat window they will be turned to a normal <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> note, revealing the underlying JSON of the conversation.</p><h3>Reintroduction in v0.103.0</h3><p>Given the recent advancements of the AI scene, we decided to give the LLM integration another try. v0.103.0 introduces a completely new chat system.</p><p>One of the key changes that lead to the reimplementation is that now we are using a library (<a href=\"https://github.com/vercel/ai\">Vercel AI</a>) to manage the inner mechanism and the differences between LLM providers instead of having to implement it on our own.</p>","_help_bkPZAMT7d2sR": "<p>Providers are added in the <em>Model Providers</em> section of the AI settings, with <em>Add Model Provider</em>. Each one lists the models selected for it, which are the ones the chat offers; a provider with no models selected is not offered in the chat.</p><h2>Cloud providers using API keys</h2><p>Currently, the following cloud providers are supported:</p><ul><li><span class=\"tn-icon tn-brand tn-brand-anthropic\"></span> <a href=\"https://platform.claude.com/settings/workspaces/default/keys\">Anthropic</a></li><li><span class=\"tn-icon tn-brand tn-brand-openai\"></span> OpenAI</li><li><span class=\"tn-icon tn-brand tn-brand-gemini\"></span> Gemini</li><li><span class=\"tn-icon tn-brand tn-brand-deepseek\"></span> DeepSeek</li><li><span class=\"tn-icon tn-brand tn-brand-openrouter\"></span> <a href=\"https://openrouter.ai/settings/keys\">OpenRouter</a></li></ul><p>For all the providers, an API key is needed. Note that this is charged separately from the subscription you might already have (e.g. Claude Pro). If that might be a problem, consider using either a subscription provider (see below) or using it externally via MCP.</p><p>Do note that most other LLM providers (e.g. Groq, Mistral, Together) can still be used in Trilium via the OpenAI-compatible custom endpoint (see below).</p><p>If you are using a proxy or gateway, you can also configure the base URL, otherwise the default will be used.</p><p>For OpenRouter, the models are billed to your OpenRouter credits, and their prices, context windows and the attachments they read come from OpenRouter's own model list:</p><ul><li>The <em>Latest</em> models that can use tools are selected by default, such as <em>Anthropic: Claude Sonnet Latest</em>. OpenRouter points each of them at the newest model of its line, so the selection stays current without editing the provider.</li><li>Models that reason have a reasoning effort dropdown in the chat (<em>Low</em>, <em>Medium</em> or <em>High</em>).</li><li><em>Auto Router</em> (<code>openrouter/auto</code>) picks a model for each message. Below each reply, the chat names the model that wrote it, which is also the case when a <em>Latest</em> model was used.</li><li>The cost shown below a reply is what OpenRouter billed for it, rather than an estimate from the listed prices.</li><li>Image generation models and the deferred <em>batch</em> variants are not listed.</li><li>Chat titles are generated with <em>Anthropic: Claude Haiku Latest</em>.</li><li>Requests are attributed to Trilium on your OpenRouter activity page.</li></ul><p>For Gemini, a chat that doesn't specify a model uses <code>gemini-3.8-flash</code>, and the automatically generated chat titles use <code>gemini-3.5-flash-lite</code>. A model you select explicitly is used as is and isn't affected by these defaults.</p><aside class=\"admonition note\"><p>We don't plan to support all cloud providers, even if the library we are using would theoretically support them. Before opening a PR adding support for a different cloud provider, make sure to discuss it over <a href=\"https://github.com/orgs/TriliumNext/discussions\">GitHub Discussions</a>.</p></aside><aside class=\"admonition important\"><p>See also the dedicated <a class=\"reference-link\" href=\"#root/_help_cRRrdZjgyhNc\">Privacy</a> section to better understand what data is being sent to a cloud provider.</p></aside><h2>Subscription-based providers</h2><p>Trilium integrates multiple <a class=\"reference-link\" href=\"#root/_help_eFhxp9laTW1S\">Subscription-based providers</a>:</p><ul><li><span class=\"tn-icon tn-brand tn-brand-claude\"></span> Claude Code by reusing your CLI.</li><li><span class=\"tn-icon tn-brand tn-brand-github-copilot\"></span> GitHub Copilot by reusing your CLI's ACP.</li><li><span class=\"tn-icon tn-brand tn-brand-antigravity\"></span> Google Antigravity by downloading and setting up an ACP for Trilium.</li><li><span class=\"tn-icon tn-brand tn-brand-codex\"></span> OpenAI Codex by reusing your CLI through an ACP adapter shipped with Trilium.</li></ul><h2>Local/self-hosted providers</h2><p>Local or self-hosted providers are a free alternative which respects your privacy but requires specific hardware.</p><p>Trilium directly supports the following local providers:</p><div class=\"trilium-tabs\"><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon tn-brand tn-brand-ollama\"></span> Ollama</p><div class=\"trilium-tab-panel\"><p>Generally Ollama runs in the background so it should be directly usable in Trilium as long as the models are downloaded (e.g. <code>ollama pull llama3.2</code>).</p></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon tn-brand tn-brand-lmstudio\"></span> LM Studio</p><div class=\"trilium-tab-panel\"><p>The OpenAI-compatible server is <strong>disabled</strong> by default in LM Studio installations. First download your desired models through the graphical interface, then go to <em>Settings</em> → <em>Developer</em> and toggle <em>Developer mode</em>. On the left there will be a new <em>Developer</em> tab, with a toggle to start it up.</p></div></section></div><p>Even for local providers that are not directly supported by Trilium, you can still use a custom endpoint (see below).</p><aside class=\"admonition warning\"><p>When dealing with self-hosted LLM models, depending on the training and the size of the model, the quality of the output may vary. Before <a href=\"#root/_help_wy8So3yZZlH9\">reporting issues</a> regarding the quality of the output (e.g. hallucinating tool calls), consider benchmarking the response against a cloud provider (Claude Sonnet is recommended).</p></aside><h2>Custom endpoints</h2><p>If your desired hosted (e.g. Groq, Mistral, Together) or local LLM provider is not listed in Trilium, you can use the dedicated <em>OpenAI-compatible</em> provider from the <em>Custom endpoint</em> section.</p><p>This allows you to set the base URL to an OpenAI-compatible API, with an optional API key if required by the service.</p><p>Enter the base URL exactly as the service documents it, including its version path, such as <code>https://api.groq.com/openai/v1</code> or <code>https://open.bigmodel.cn/api/paas/v4</code>. Only a bare host such as <code>http://localhost:8080</code> is completed with <code>/v1</code>.</p><p>The endpoint can run on the same machine as Trilium, elsewhere on your local network or on a Tailscale tailnet. Trilium refuses link-local addresses (<code>169.254.0.0/16</code>) and cloud metadata endpoints, which no model server is served on.</p><p>For custom endpoints, the pricing of the models is not known so the cost of a conversation will not be displayed; this is especially relevant for hosted providers.</p>","_help_eFhxp9laTW1S": "<p>Some cloud providers offer a subscription, which has a fixed monthly fee instead of pay-per-use (unlike the API keys).</p><p>In a nutshell, subscription-based providers work by either reusing your existing CLI tools (e.g. Claude Code, GitHub Copilot and OpenAI Codex via ACP) whereas some require installing the ACP server manually (e.g. Google Antigravity). Because they require something to be installed on your device, these providers are not available on Mobile (Android or iOS) or standalone mode.</p><p>See also the dedicated <a class=\"reference-link\" href=\"#root/_help_cRRrdZjgyhNc\">Privacy</a> section to better understand what data is being sent to a cloud provider.</p><h2>Using the Flatpak</h2><p>The Flatpak version of Trilium (see <a href=\"#root/_help_poXkQfguuA0U\">Installing from Flathub</a>) runs in a sandbox that hides the programs installed on your computer, so on its own it cannot find Claude Code, the GitHub Copilot CLI, the Codex CLI or Google's Antigravity ACP server. Trilium can start them outside the sandbox once you allow it to:</p><ol><li><p>Install the CLI on your computer and sign in to it, as described below for each provider.</p></li><li><p>Allow Trilium to start programs outside its sandbox by running this in a terminal:</p><pre><code class=\"language-text-x-sh\">flatpak override --user --talk-name=org.freedesktop.Flatpak org.triliumnotes.Trilium</code></pre></li><li><p>Restart Trilium, then go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em> and add the provider.</p></li></ol><p>Trilium then looks the CLI up in your computer's <code>PATH</code> and in your login shell's, and starts it there through <code>flatpak-spawn --host</code>. Until the permission is granted, adding one of these providers fails with a message that repeats these steps.</p><aside class=\"admonition warning\"><p>This permission lets Trilium run any program on your computer outside the sandbox, which is the same access an installation outside Flatpak has. To take it back, run <code>flatpak override --user --no-talk-name=org.freedesktop.Flatpak org.triliumnotes.Trilium</code> and restart Trilium.</p></aside><p>The environment variables that point Trilium at a CLI (such as <code>TRILIUM_CLAUDE_CODE_PATH</code>) name a file inside the sandbox, so with the Flatpak, leave them unset and let Trilium find the CLI on your computer.</p><h2><span class=\"tn-icon tn-brand tn-brand-claude\"></span> Claude Code</h2><p>To use a subscription:</p><ol><li>First, Claude Code needs to be installed on the machine that runs Trilium. So for a <a class=\"reference-link\" href=\"#root/_help_poXkQfguuA0U\">Desktop Installation</a>, Claude needs to be installed locally and for a <a class=\"reference-link\" href=\"#root/_help_WOcw2SLH6tbX\">Server Installation</a> accessed via a browser, Claude needs to be installed on the server.</li><li>Claude Code must already be authenticated. To do so, run <code>claude</code> in a terminal once, type <code>/login</code> and follow the instructions.</li><li>Go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em> and add the Claude Code provider.</li></ol><details class=\"trilium-collapsible\"><summary>How Trilium identifies your Claude Code binary</summary><p>In this order:</p><ul><li>By looking for a <code>TRILIUM_CLAUDE_CODE_PATH</code> environment variable pointing to the Claude binary. This allows overriding the path if needed.</li><li>By looking for <code>claude</code> in your PATH, generally works in most circumstances.</li><li>By asking your login shell for its <code>PATH</code> which lets a desktop install find a CLI installed through <code>nvm</code>, <code>fnm</code>, <code>asdf</code> or Homebrew, since a GUI-launched app doesn't inherit your terminal's environment.</li></ul></details><p>After your provider is set up, you'll benefit from the same features as an API key (note tools, web search, extended thinking, image/PDF attachments, streaming).</p><aside class=\"admonition note\"><p>Trilium intentionally uses your Claude Code binary in order not to have to package a ~250 MB client with it, but this comes at a cost: there is a small risk for a version incompatibility, if the version installed locally doesn't match the one expected by Trilium. Generally it's best to keep both Claude Code and Trilium updated to the latest version.</p></aside><h2><span class=\"tn-icon tn-brand tn-brand-github-copilot\"></span> GitHub Copilot</h2><aside class=\"admonition note\"><p>This subscription-based provider is still in beta. It is safe to use (won't use additional funds and respects the terms of use), but you might experience small issues. Consider <a class=\"reference-link\" href=\"#root/_help_wy8So3yZZlH9\">Reporting issues</a>.</p></aside><p>GitHub Copilot gives access to the models of your GitHub Copilot subscription (Pro, Pro+, Business or Enterprise), without an API key. Usage counts against your Copilot plan.</p><ol><li>Install the GitHub Copilot CLI on the machine that runs Trilium, for example with <code>npm install -g @github/copilot</code>. As with Claude Code, for a <a class=\"reference-link\" href=\"#root/_help_WOcw2SLH6tbX\">Server Installation</a> it needs to be installed on the server.</li><li>Sign in by running <code>copilot login</code> in a terminal once. If you already use GitHub Copilot in another editor on the same machine, that login is reused.</li><li>Go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em> and add the GitHub Copilot provider.</li></ol><details class=\"trilium-collapsible\"><summary>How Trilium identifies your Copilot CLI binary</summary><p>In this order:</p><ul><li>By looking for a <code>TRILIUM_COPILOT_PATH</code> environment variable pointing to the Copilot binary.</li><li>By looking for <code>copilot</code> in your PATH.</li><li>By asking your login shell for its <code>PATH</code>, the same as for Claude Code.</li></ul></details><h3>Known limitations</h3><ul><li>The agent can only work with your notes through Trilium's note tools; its own file, shell and web tools are blocked for security reasons.</li><li>Images can be attached to the conversation, PDFs cannot. The LLM should still be able to read PDF notes and attachments via <a class=\"reference-link\" href=\"#root/_help_TiQbQDgP8L5t\">Text Extraction (OCR)</a> when the note tools are enabled.</li></ul><h2><span class=\"tn-icon tn-brand tn-brand-antigravity\"></span> Google Antigravity</h2><aside class=\"admonition note\"><p>This subscription-based provider is still in beta. It is safe to use (won't use additional funds and respects the terms of use), but you might experience small issues. Consider <a class=\"reference-link\" href=\"#root/_help_wy8So3yZZlH9\">Reporting issues</a>.</p></aside><p>Google Antigravity gives access to Gemini models using a Google account (free, Google AI Pro or Google AI Ultra), without an API key. At the time of writing, a free Google account is enough to use it.</p><p>Unlike Claude Code or GitHub Copilot, Google's Antigravity ACP server is not part of the CLI so it needs to be installed manually just for Trilium. The downloaded archive is around 112-334 MB and the extracted size is around 230 MB-2 GB based on the platform.</p><div class=\"trilium-tabs\"><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bxl-windows\"></span> Windows</p><div class=\"trilium-tab-panel\"><ol><li>Download Google's Antigravity ACP server for your platform. The link is shown when adding the provider in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em>. Unpack it on the device that runs Trilium.</li><li>Make it findable by Trilium, either:<ol><li>by adding the unpacked folder to your PATH, or</li><li>by setting a <code>TRILIUM_ANTIGRAVITY_ACP_PATH</code> environment variable pointing to <code>agy_acp_server.exe</code>.</li></ol></li><li>Go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → AI / LLM and add the <span class=\"tn-icon tn-brand tn-brand-antigravity\"></span> <em>Google Antigravity</em> provider. When the list of models is loaded for the first time, the Google sign-in page opens in a browser on the machine running Trilium; finish signing in there.</li></ol></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bxl-tux\"></span> Linux & <span class=\"tn-icon bx bxl-apple\"></span> macOS</p><div class=\"trilium-tab-panel\"><ol><li>Download Google's Antigravity ACP server for your platform. The link is shown when adding the provider in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em>. Unpack it on the device that runs Trilium.</li><li>Make it findable by Trilium, either:<ol><li>by adding the unpacked folder to your PATH, or</li><li>by setting a <code>TRILIUM_ANTIGRAVITY_ACP_PATH</code> environment variable pointing to <code>agy_acp_server.par</code>.</li></ol></li><li>Go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → AI / LLM and add the <span class=\"tn-icon tn-brand tn-brand-antigravity\"></span> <em>Google Antigravity</em> provider. When the list of models is loaded for the first time, the Google sign-in page opens in a browser on the machine running Trilium; finish signing in there.</li></ol></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\">NixOS</p><div class=\"trilium-tab-panel\"><ol><li><p>On NixOS, <code>antigravity-acp</code> package is already available but only in <code>nixos-unstable</code> at the time of writing. The easiest method to test it out is to use the <code>nix shell</code> with flakes:</p><pre><code class=\"language-text-x-trilium-auto\">NIXPKGS_ALLOW_UNFREE=1 nix shell --impure github:nixos/nixpkgs/nixos-unstable#antigravity-acp\ntrilium</code></pre></li><li><p>Go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → AI / LLM and add the <span class=\"tn-icon tn-brand tn-brand-antigravity\"></span> <em>Google Antigravity</em> provider. When the list of models is loaded for the first time, the Google sign-in page opens in a browser on the machine running Trilium; finish signing in there.</p></li></ol></div></section></div><aside class=\"admonition note\"><p>Trilium needs <code>curl</code> to use Google Antigravity. It comes with Windows 10 and later, macOS and most Linux distributions.</p></aside><h3>Known limitations</h3><ul><li>The agent can only work with your notes through Trilium's note tools; its own file and shell tools are blocked for security reasons.</li><li>The Antigravity ACP server requires authentication via a login link. The login link needs to be run on the same device, so it might not be possible to set up the provider while using the web version of a Docker installation. <a class=\"reference-link\" href=\"#root/_help_poXkQfguuA0U\">Desktop Installation</a> should work fine.</li><li>Images can be attached to the conversation, PDFs cannot. The LLM should still be able to read PDF notes and attachments via <a class=\"reference-link\" href=\"#root/_help_TiQbQDgP8L5t\">Text Extraction (OCR)</a> when the note tools are enabled.</li><li>The results of tool calls (e.g. reading a note, writing attributes) are not properly displayed because they are not exposed by the ACP server.</li></ul><h2><span class=\"tn-icon tn-brand tn-brand-codex\"></span> OpenAI Codex</h2><aside class=\"admonition note\"><p>This subscription-based provider is still in beta. It is safe to use (won't use additional funds and respects the terms of use), but you might experience small issues. Consider <a class=\"reference-link\" href=\"#root/_help_wy8So3yZZlH9\">Reporting issues</a>.</p></aside><p>OpenAI Codex gives access to the Codex models of your ChatGPT plan (Free, Go, Plus, Pro or Business), without an API key. At the time of writing, a free ChatGPT account is enough to use it. Usage counts against your plan's Codex limits, which are small on the Free plan.</p><div class=\"trilium-tabs\"><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bxl-windows\"></span><span class=\"tn-icon bx bxl-tux\"></span><span class=\"tn-icon bx bxl-apple\"></span> Most platforms</p><div class=\"trilium-tab-panel\"><ol><li>Install the Codex CLI on the machine that runs Trilium, for example with <code>npm install -g @openai/codex</code>. As with Claude Code, for a <a class=\"reference-link\" href=\"#root/_help_WOcw2SLH6tbX\">Server Installation</a> it needs to be installed on the server. Trilium ships the ACP adapter that connects to it, so nothing else is needed.</li><li>Go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em> and add the <span class=\"tn-icon tn-brand tn-brand-codex\"></span> <em>OpenAI Codex</em> provider. When the list of models is loaded for the first time, the ChatGPT sign-in page opens in a browser on the machine running Trilium; finish signing in there.</li></ol></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\">NixOS</p><div class=\"trilium-tab-panel\"><ol><li><p>On NixOS, Codex is available as the <code>codex</code> package in nixpkgs. The stable channel can lag behind Codex's releases, so a newer version can be taken from <code>nixos-unstable</code>:</p><pre><code class=\"language-text-x-sh\">nix shell github:nixos/nixpkgs/nixos-unstable#codex\ntrilium</code></pre></li><li><p>Go to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em> and add the <span class=\"tn-icon tn-brand tn-brand-codex\"></span> <em>OpenAI Codex</em> provider. When the list of models is loaded for the first time, the ChatGPT sign-in page opens in a browser on the machine running Trilium; finish signing in there.</p></li></ol></div></section></div><p>Trilium keeps its own Codex sign-in and settings, separate from any Codex CLI you use in a terminal, so an existing <code>codex login</code> is not reused.</p><details class=\"trilium-collapsible\"><summary>How Trilium identifies your Codex CLI binary</summary><p>In this order:</p><ul><li>By looking for a <code>TRILIUM_CODEX_PATH</code> environment variable pointing to the Codex binary.</li><li>By looking for <code>codex</code> in your PATH.</li><li>By asking your login shell for its <code>PATH</code>, the same as for Claude Code.</li></ul></details><aside class=\"admonition note\"><p>Trilium needs <code>curl</code> to use OpenAI Codex, the same as for Google Antigravity: Trilium checks every tool call Codex makes through it. It comes with Windows 10 and later, macOS and most Linux distributions.</p></aside><h3>Known limitations</h3><ul><li>The agent can only work with your notes through Trilium's note tools, and search the web when the chat allows it; its own file, shell and other tools are blocked for security reasons.</li><li>The ChatGPT sign-in opens in a browser on the device running Trilium, so it might not be possible to set up the provider while using the web version of a Docker installation. <a class=\"reference-link\" href=\"#root/_help_poXkQfguuA0U\">Desktop Installation</a> should work fine.</li><li>Images and SVGs can be attached to the conversation, PDFs cannot. The LLM should still be able to read PDF notes and attachments via <a class=\"reference-link\" href=\"#root/_help_TiQbQDgP8L5t\">Text Extraction (OCR)</a> when the note tools are enabled.</li></ul>","_help_cRRrdZjgyhNc": "<p>Trilium sends nothing to an AI provider until you send a message. Enabling the integration, adding a provider or opening a chat transmits nothing on its own, the one exception is that listing a provider's models sends your API key to that provider, so the list can be fetched.</p><p>Once you send a message or run the <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a>, what leaves your machine depends on the provider you chose and on which context options are enabled.</p><h2>Where your notes go</h2><figure class=\"table\"><table><thead><tr><th>Provider type</th><th>Destination</th></tr></thead><tbody><tr><td>Cloud providers</td><td>The provider's servers (Anthropic, OpenAI, Google, DeepSeek). OpenRouter passes each message on to the lab that runs the chosen model, according to the privacy settings of your OpenRouter account.</td></tr><tr><td>Subscription-based</td><td>The provider's servers, via Claude Code running locally</td></tr><tr><td>Local / self-hosted</td><td>Nothing leaves the machine running the model</td></tr><tr><td>Custom endpoint</td><td>Wherever it was pointed, which may be your own hardware or a hosted service</td></tr></tbody></table></figure><p>This is the reason the provider list is grouped this way, and why Trilium pre-selects nothing: the choice of where your note content is sent is made explicitly by you, before anything is sent.</p><aside class=\"admonition note\"><p>The <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a> has a model selection of its own, so it may be answered by a different provider than the one in the chat. The row at the bottom of the assistant's menu always names the one being used.</p></aside><h2>What is actually sent</h2><ul><li><strong>Always, with every message</strong><ul><li>The conversation itself: your messages and the assistant's replies, including earlier turns</li><li>Trilium's system prompt describing how to format answers and use tools.</li></ul></li><li><strong>The current note, only when note context is enabled.</strong><ul><li>In the sidebar chat this is the file icon at the bottom; the dedicated chat note type never sends a current note.</li><li>What travels is a metadata block: the note's ID, title, type, creation and modification dates, its parent IDs, the titles of up to 20 children, up to 20 attributes, and a preview of the content.</li><li>Notes above a size threshold send a size hint instead of the text, and the model must call a tool to read further.</li></ul></li><li><strong>Any note the model asks for, when note access is enabled.</strong><ul><li>Tools let the model search your tree and read notes, attributes and attachments beyond the current one.</li><li>It decides what to fetch, and each call waits for you to allow it, unless the chat's permission mode lets reads or every call run on their own, or you allowed that tool for the chat. The reachable scope is your whole tree, except for notes you exclude (see <em>Excluding notes</em> below).</li></ul></li><li><strong>Attachments and mentions</strong>, when you add them: images, PDFs and text files are sent to the provider, and an <code>@</code> mention makes that note fetchable.</li><li><strong>Your search query</strong>, when web search is enabled, the model's search terms reach the provider's own search infrastructure, or the search provider chosen in the <em>Tools</em> menu (Brave Search, Tavily, Exa, Serper, Perplexity or your SearXNG instance).</li><li><strong>The pages the model reads</strong>, when web search goes through a search provider or a DeepSeek model's built-in search: Trilium fetches each page the model asks for from the site itself, so the site sees a request from the machine running Trilium. The page's text is then sent to the model's provider.</li></ul><h2>The in-editor AI assistant</h2><p>A run of the <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a> sends a different set than a chat message. For quick actions, it sends it the moment you pick an action, there is no send button to reconsider at. For the free-form <em>Ask AI</em>, there is a dedicated send button and model selector.</p><ul><li><strong>The passage you selected</strong>, or the paragraph the cursor is in when you pick a quick action without selecting anything.</li><li><strong>Up to 1500 characters of the note on each side of that passage</strong>, as plain text. The assistant is told this is context only and must not be rewritten, but it is sent regardless of whether you selected it: a run on a single sentence still transmits the paragraphs around it.</li><li><strong>Where the note sits</strong>: its title and the titles of its parents, as a breadcrumb.</li><li><strong>Trilium's writing-assistant instructions</strong>, which describe the formatting it may produce.</li><li><strong>Earlier turns of the same exchange</strong>, once you follow up on a response.</li></ul><p>No note metadata block is sent, web search is never enabled, and the assistant has no note tools so it can read nothing beyond the text listed above.</p><h2>Protected notes</h2><p>While your <a href=\"#root/_help_bwg0e8ewQMak\">protected session</a> is locked, protected notes send neither title nor content. <strong>While it is unlocked they are treated like any other note,</strong> a note the model reads through a tool is sent to the provider in full. If you keep sensitive material in protected notes, be aware that unlocking them removes that boundary for the duration of the session.</p><p>The same applies to the <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a>: it works on whatever is open in the editor, so running it inside an unlocked protected note sends that note's text like any other.</p><h2>Excluding notes</h2><p>Add the <code>#excludeFromLlm</code> <a href=\"#root/_help_HI6GBBIduIgv\">label</a> to a note to hide it from the AI chat and the <a href=\"#root/_help_KOWBFgsZXJAD\">MCP server</a>. The label covers only that note: the notes below it stay visible unless you make the label <a href=\"#root/_help_bwZpz2ajCEwO\">inheritable</a>, and a child can opt back in with <code>#excludeFromLlm=false</code>.</p><p>A note created from a template inherits all of the template's labels (see <a class=\"reference-link\" href=\"#root/_help_KC1HB96bqqHX\">Templates</a>), so adding <code>#excludeFromLlm</code> to a template hides every note that uses it, not just the template.</p><p>For an excluded note:</p><ul><li>The note tools report it as not found: it is left out of search results, child lists and subtrees, and relations that point to it are not shown.</li><li>The model cannot read, edit, move, clone or rename it, create notes under it, or remove the label. It also cannot delete a note that has an excluded note below it.</li><li>Its metadata is not sent as the current note, even when note context is enabled.</li><li>A visible child does not show it as a parent, and the model cannot move the child out of it.</li></ul><p>Unlike a protected note, an excluded note stays hidden while your protected session is unlocked. The exclusion applies to the note tools only. It is not encryption, and it does not cover:</p><ul><li>Files you attach to a message yourself.</li><li>The <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a> when you run it inside the note.</li><li>Text from the note that appears in other notes, such as a link with the note's title.</li><li>What a search query can test. Search never returns an excluded note, but a query can still match a visible note through an excluded one: by its title in the note path, through a relation (<code>~link.title</code>), a parent or child (<code>note.parents.content</code>), or a label the visible note inherits from it. A model that guesses can learn whether an excluded note contains a given word.</li></ul><h2>What you control</h2><ul><li><strong>Which provider</strong>: the single decision that determines whether anything leaves your machine at all.</li><li><strong>Note access</strong>: turn it off in the <span class=\"tn-icon bx bx-shield-quarter\"></span><em>Tools</em> menu at the bottom of the chat, and the model can read nothing beyond what you type.</li><li><strong>The current note:</strong> the file icon in the sidebar chat.</li><li><strong>Notes the AI cannot reach:</strong> the <code>#excludeFromLlm</code> label, see <em>Excluding notes</em> above.</li><li><strong>Web search:</strong> also in the <em>Tools</em> menu.</li><li><strong>Which tool calls ask first:</strong> the <em>Permissions</em> submenu of the <em>Tools</em> menu. <em>Always ask</em> has every call wait for you, reads included. A new chat starts in the mode you picked last, so a chat after one set to <em>Don't ask</em> asks about nothing either. Until you pick a mode, chats start in <em>Ask before changes</em>, where the AI reads and searches your notes without asking.</li><li><strong>The editor assistant</strong>: it has no per-run toggles. What you control is whether you run it, what you select before you do and which model answers.</li></ul><p>With note access and note context both off, the provider receives only the words you typed.</p><h2>Keeping everything local</h2><p>Adding an Ollama or LM Studio provider keeps every message on the machine running the model, and Trilium marks their models as free because no metered API is involved. The trade-off is quality and hardware: a small local model may fail at tool calls that a cloud model handles, so a local setup that misbehaves is worth benchmarking against a cloud provider before reporting it as a bug.</p><h2>Telemetry & security</h2><p>Trilium itself collects no telemetry from the AI integration.</p><p>Your API key is stored in your database, sent only to the provider it belongs to, and is write-only through the options API so that a malevolent <a class=\"reference-link\" href=\"#root/_help_CdNpE2pqjmI6\">Scripting</a> cannot access it. If you have backend or SQL console access enabled, a malevolent script <strong>could potentially exfiltrate your API keys</strong>.</p><p>The built-in MCP server is off by default. When enabled, every request must carry an ETAPI token, which grants the same full read and write access to your notes as the REST API; treat one like a password. On desktop it is reachable only from <code>localhost</code> unless you turn on <a class=\"reference-link\" href=\"#root/_help_swSFivWk6KkA\">Network Access</a>.</p>",diff --git a/docs/User Guide/User Guide/AI.md b/docs/User Guide/User Guide/AI.mdindex 27240d113d..0b2e03faaf 100644--- a/docs/User Guide/User Guide/AI.md+++ b/docs/User Guide/User Guide/AI.md@@ -154,8 +154,8 @@ Here are a few tools that Trilium provides for the LLM:* Rename or delete a note.* At attribute level:* Get the full list of attributes, or a specific attribute.- * Set the value of an attribute.- * An attribute that runs code, such as `#run`, `#widget` or `~renderNote`, is saved with a `disabled:` prefix (for example `#disabled:widget`), the same way a safe import disables it (see <a class="reference-link" href="Basic%20Concepts%20and%20Features/Active%20content.md">Active content</a>). If the note already had that attribute enabled, the AI removes it, so none of it runs until you enable the new value. The AI tells you which note it is on; review the code, then enable it with the toggle next to the active content badge beside the note's title or, for a <a class="reference-link" href="Note%20Types/Render%20Note.md">Render Note</a>, the _Enable render note_ button in the note.+ * Set the value of an attribute, or add another value next to the existing ones (such as a second `#tag`). When setting a value replaces an existing one, the AI is told which value it replaced.+ * An attribute that runs code, such as `#run`, `#widget` or `~renderNote`, is saved with a `disabled:` prefix (for example `#disabled:widget`), the same way a safe import disables it (see <a class="reference-link" href="Basic%20Concepts%20and%20Features/Active%20content.md">Active content</a>). If the note already had that attribute enabled and the AI sets rather than adds the value, the AI removes the enabled one, so none of it runs until you enable the new value. The AI tells you which note it is on; review the code, then enable it with the toggle next to the active content badge beside the note's title or, for a <a class="reference-link" href="Note%20Types/Render%20Note.md">Render Note</a>, the _Enable render note_ button in the note.* Delete an attribute.* At tree level:* Get the direct children of a note.diff --git a/packages/trilium-core/src/services/llm/tools/attribute_tools.spec.ts b/packages/trilium-core/src/services/llm/tools/attribute_tools.spec.tsindex 71cae138e7..13b9465119 100644--- a/packages/trilium-core/src/services/llm/tools/attribute_tools.spec.ts+++ b/packages/trilium-core/src/services/llm/tools/attribute_tools.spec.ts@@ -102,6 +102,55 @@ describe("attribute_tools", () => {expect(result.value).toBe("");});+ it("appends same-name labels in add mode instead of replacing them", () => {+ const note = createNote("Add mode host");+ for (const value of [ "MCP", "AI", "Blender" ]) {+ const result = cls.init(() => getTool("set_attribute").execute({+ noteId: note.noteId, type: "label", name: "tag", value, mode: "add"+ }));+ expect(result).toEqual({+ success: true, noteId: note.noteId, type: "label", name: "tag", value+ });+ }+ expect(note.getOwnedLabels("tag").map((l) => l.value)).toEqual([ "MCP", "AI", "Blender" ]);+ });++ it("reports the value it replaced in set mode", () => {+ const note = createNote("Replace host");+ cls.init(() => note.addLabel("tag", "MCP"));++ const result = cls.init(() => getTool("set_attribute").execute({+ noteId: note.noteId, type: "label", name: "tag", value: "Blender"+ }));+ expect(result).toMatchObject({+ success: true, value: "Blender", previousValue: "MCP",+ message: expect.stringContaining("mode \"add\"")+ });+ expect(note.getOwnedLabels("tag").map((l) => l.value)).toEqual([ "Blender" ]);++ const unchanged = cls.init(() => getTool("set_attribute").execute({+ noteId: note.noteId, type: "label", name: "tag", value: "Blender"+ }));+ expect(unchanged).not.toHaveProperty("previousValue");+ expect(unchanged).not.toHaveProperty("message");+ });++ it("names the same-name labels it left untouched in set mode", () => {+ const note = createNote("Several tags host");+ cls.init(() => {+ note.addLabel("tag", "MCP");+ note.addLabel("tag", "AI");+ });++ const result = cls.init(() => getTool("set_attribute").execute({+ noteId: note.noteId, type: "label", name: "tag", value: "Blender"+ }));+ expect(result).toMatchObject({+ previousValue: "MCP", message: expect.stringContaining("1 other #tag")+ });+ expect(note.getOwnedLabels("tag").map((l) => l.value)).toEqual([ "Blender", "AI" ]);+ });+it("rejects a missing note, protected note, and missing relation target", () => {expect(getTool("set_attribute").execute({ noteId: "missing", type: "label", name: "x" })).toEqual({ error: "Note not found" });@@ -160,6 +209,23 @@ describe("attribute_tools", () => {expect(note.getOwnedLabelValue("disabled:run")).toBe("hourly");});+ it("keeps active and disabled dangerous attributes when adding a disabled one", () => {+ const note = createNote("Add danger host");+ cls.init(() => {+ note.addLabel("run", "frontendStartup");+ note.addLabel("disabled:run", "backendStartup");+ });++ const result = cls.init(() => getTool("set_attribute").execute({+ noteId: note.noteId, type: "label", name: "run", value: "hourly", mode: "add"+ }));+ expect(result).toMatchObject({ success: true, name: "disabled:run", disabled: true });+ expect((result as { message: string }).message).not.toContain("removed");+ expect(note.getOwnedLabels("run").map((l) => l.value)).toEqual([ "frontendStartup" ]);+ expect(note.getOwnedLabels("disabled:run").map((l) => l.value))+ .toEqual([ "backendStartup", "hourly" ]);+ });+it("creates a relation to an existing target note", () => {const note = createNote("Relation ok host");const result = cls.init(() => getTool("set_attribute").execute({diff --git a/packages/trilium-core/src/services/llm/tools/attribute_tools.ts b/packages/trilium-core/src/services/llm/tools/attribute_tools.tsindex 00fbd893ff..5d7b9193ae 100644--- a/packages/trilium-core/src/services/llm/tools/attribute_tools.ts+++ b/packages/trilium-core/src/services/llm/tools/attribute_tools.ts@@ -56,15 +56,16 @@ export const attributeTools = defineTools({},set_attribute: {- description: "Add or update an attribute on a note. If an attribute with the same type and name exists, it is updated; otherwise a new one is created. Use type 'label' for text values, 'relation' for linking to another note (value must be a noteId). Attributes that run code (such as #run, #widget, ~renderNote) are saved with a 'disabled:' prefix (e.g. #disabled:run) and stay inactive until the user enables them; when that happens, tell the user which note to open and how to enable it (the reply says how).",+ description: "Add or update an attribute on a note. In the default mode 'set', an existing attribute with the same type and name is updated (the reply gives the value it replaced); otherwise a new one is created. Mode 'add' always creates a new attribute, so a note can carry several values of one name (e.g. #tag=MCP and #tag=Blender). Use type 'label' for text values, 'relation' for linking to another note (value must be a noteId). Attributes that run code (such as #run, #widget, ~renderNote) are saved with a 'disabled:' prefix (e.g. #disabled:run) and stay inactive until the user enables them; when that happens, tell the user which note to open and how to enable it (the reply says how).",inputSchema: z.object({noteId: z.string().describe("The ID of the note"),type: z.enum(["label", "relation"]).describe("The attribute type"),name: z.string().describe("The attribute name"),- value: z.string().optional().describe("The attribute value (for relations, this must be a target noteId)")+ value: z.string().optional().describe("The attribute value (for relations, this must be a target noteId)"),+ mode: z.enum(["set", "add"]).optional().describe("'set' (default) updates the existing attribute of this name; 'add' creates another one next to it, for multi-valued labels such as #tag")}),mutates: true,- execute: ({ noteId, type, name, value = "" }) => {+ execute: ({ noteId, type, name, value = "", mode = "set" }) => {const note = getLlmNote(noteId);if (!note) {return { error: "Note not found" };@@ -76,15 +77,20 @@ export const attributeTools = defineTools({return { error: "Target note not found for relation" };}+ const sigil = type === "label" ? "#" : "~";+if (attributeService.isAttributeDangerous(type, name)) {- const sigil = type === "label" ? "#" : "~";const disabledName = `disabled:${name.trim()}`;// An active attribute left in place would keep running its old value while the reply says it is inactive.- const activeAttributes = note.getOwnedAttributes(type, name.trim());+ const activeAttributes = mode === "set" ? note.getOwnedAttributes(type, name.trim()) : [];for (const attribute of activeAttributes) {attribute.markAsDeleted();}- note.setAttribute(type, disabledName, value);+ if (mode === "add") {+ note.addAttribute(type, disabledName, value);+ } else {+ note.setAttribute(type, disabledName, value);+ }return {success: true,@@ -102,14 +108,28 @@ export const attributeTools = defineTools({};}+ const result = { success: true, noteId: note.noteId, type, name, value };++ if (mode === "add") {+ note.addAttribute(type, name, value);+ return result;+ }++ const [ existing, ...others ] = note.getOwnedAttributes(type, name);+ const previousValue = existing?.value;note.setAttribute(type, name, value);+ if (previousValue === undefined || previousValue === value) {+ return result;+ }return {- success: true,- noteId: note.noteId,- type,- name,- value+ ...result,+ previousValue,+ message: `Replaced ${sigil}${name}=${previousValue}. `+ + (others.length+ ? `${others.length} other ${sigil}${name} ${others.length === 1 ? "attribute was" : "attributes were"} left unchanged. `+ : "")+ + `To keep several values of ${sigil}${name}, use mode "add" instead.`};}},