Tolaria Complete Guide 2026: Open-Source Markdown Knowledge Base Desktop App

What Is Tolaria?

Tolaria is an open-source desktop application for managing Markdown-based knowledge bases. Created by developer Luca Ronin, it was originally built to manage his personal workspace of over 10,000 notes. It has since grown into a popular project with 14,000+ stars on GitHub.

Core Philosophy

Tolaria's design philosophy is clear: your data belongs to you, not to any app. This sets it apart from mainstream note-taking tools like Obsidian and Notion:

Why Choose Tolaria?

1. Zero Lock-in: All notes are standard .md files. You can open them anytime with VS Code, Vim, or any other editor. Even if you stop using Tolaria, you won't lose any data.

2. Git-first: Every knowledge base (Vault) is a Git repository. You automatically get version history, branch management, and remote sync capabilities. This is crucial for team collaboration or long-term knowledge accumulation.

3. AI-Native Support: Tolaria has built-in support for Claude Code, Codex CLI, and Gemini CLI. It also provides an AGENTS file to help AI assistants understand your knowledge base structure.

4. Keyboard-First Design: Designed for power users. Most operations can be done via keyboard shortcuts. The Command Palette offers a VS Code-like experience.

5. Types as Lenses: Tolaria's type system isn't a mandatory schema. It's an auxiliary tool to help you navigate and categorize notes. There are no required fields or validation restrictions.

Installing Tolaria

macOS (Homebrew Recommended)

# Install via Homebrew (easiest)
brew install --cask tolaria

# Or download from the official website
# Visit https://refactoringhq.github.io/tolaria/download/

Windows

1. Visit the Tolaria Download Page
2. Download the latest .exe installer
3. Run the installer

Note: The Windows installer is Authenticode-signed. However, on company-managed devices, you may still need IT department approval for the first installation.

Linux

# Download AppImage (recommended)
wget https://github.com/refactoringhq/tolaria/releases/latest/download/Tolaria-x86_64.AppImage
chmod +x Tolaria-x86_64.AppImage
./Tolaria-x86_64.AppImage

# Or use Flatpak (if available)
flatpak install flathub com.refactoringhq.tolaria

Building from Source

# Clone the repository
git clone https://github.com/refactoringhq/tolaria.git
cd tolaria

# Install dependencies (requires Node.js 18+)
npm install

# Run in development mode
npm run dev

# Build production version
npm run build

Quick Start: Create Your First Knowledge Base

Step 1: Initialize a Vault

When you launch Tolaria for the first time, you can choose:

1. Clone the Starter Vault: Tolaria provides a getting started vault with sample notes and tutorials.
2. Create a Blank Vault: Start from scratch.
3. Open Existing Folder: If you already have a folder of Markdown notes, you can import it directly.

# Manually create a blank vault (command-line method)
mkdir ~/my-knowledge-base
cd ~/my-knowledge-base
git init
echo "# My Knowledge Base" > README.md
git add .
git commit -m "Initial commit"

Then select "Open Existing Vault" in Tolaria and point it to this folder.

Step 2: Understand the Directory Structure

A Tolaria knowledge base is just a regular folder. A typical structure looks like this:

my-vault/
├── .git/                  # Git repository (auto-generated)
├── AGENTS.md              # AI assistant configuration file
├── types/                 # Type definitions folder
│   ├── note.type.yaml     # Note type template
│   └── task.type.yaml     # Task type template
├── inbox/                 # Inbox (quick capture for ideas)
├── projects/              # Project notes
├── areas/                 # Areas of responsibility
├── resources/             # Reference materials
└── archive/               # Archived content

Tip: This structure is inspired by the PARA Method (Projects, Areas, Resources, Archive). But you can fully customize it.

Step 3: Create Your First Note

Press Cmd/Ctrl + N in Tolaria to create a new note:

---
title: Tolaria Study Notes
type: note
created: 2026-06-10
tags:
  - tolaria
  - knowledge-base
---

# Tolaria Core Features

Tolaria is a...

## Key Features

- File-first
- Git-first
- Offline-first

## Related Links

- [[Another Note]]  <!-- Bidirectional link -->
- [Tolaria GitHub](https://github.com/refactoringhq/tolaria)

Step 4: Configure Git Remote (Optional but Recommended)

# Execute in the vault directory
cd ~/my-knowledge-base

# Add a remote repository (GitHub/GitLab/Gitee)
git remote add origin https://github.com/yourusername/my-vault.git

# Push
git push -u origin main

This gives your notes cloud backup and enables synchronization across multiple devices.

Core Features Explained

1. File-First: The Power of Pure Markdown

Tolaria's biggest advantage is that it doesn't create proprietary formats. Every note is a standard Markdown file:

# Open in any editor
code ~/my-vault/inbox/idea.md
vim ~/my-vault/projects/project-a.md

# Search with grep
grep -r "keyword" ~/my-vault/

# Batch processing
find ~/my-vault -name "*.md" -exec sed -i 's/old-word/new-word/g' {} \;

This means: - ✅ Can be modified with any text editor - ✅ Can be batch-processed with scripts - ✅ Can be put under version control - ✅ Can integrate with other tools (like static site generators)

2. Git Integration: Natural Advantage of Version History

After each note modification, Tolaria automatically detects changes and prompts you to commit. You can also operate manually:

# View changes
git status
git diff

# Commit changes
git add .
git commit -m "Update project notes"

# View history
git log --oneline

# Rollback to a specific version
git checkout <commit-hash> -- filename.md

Real-world scenario: You're writing an article and accidentally delete an important paragraph. Use git log to find the previous commit, then restore it with git checkout.

3. Bidirectional Links: Building a Knowledge Network

Tolaria supports Wiki-style bidirectional links:

# In Note A
See [[Note B]] for more details.

# In Note B
This is content referenced by [[Note A]].

In the Tolaria interface: - Click a link to jump directly - Right-click to view "Backlinks" (which notes reference the current note) - Graph view displays the relationship network between notes

4. Type System: Flexible Classification

Tolaria's Types are not mandatory schemas. They are navigation aids:

# types/note.type.yaml
name: Note
icon: 📝
color: blue
fields:
  - name: created
    type: date
  - name: tags
    type: list

---
title: My Note
type: note
created: 2026-06-10
tags:
  - learning
---

You can filter notes by type in the sidebar. But there are no required fields, and you won't get errors for missing fields.

5. Command Palette: Efficient Keyboard Operations

Press Cmd/Ctrl + P to open the Command Palette, similar to VS Code:

• Quick Open: Quickly open notes
• Create Note: Create a new note
• Search: Full-text search
• Git Commit: Commit changes
• Toggle Theme: Switch theme

Common shortcuts: - Cmd/Ctrl + N: New note - Cmd/Ctrl + P: Command Palette - Cmd/Ctrl + F: Search - Cmd/Ctrl + Shift + F: Global search - Cmd/Ctrl + [: Go back

AI Integration: Let AI Assistants Understand Your Knowledge Base

One of Tolaria's standout features is its native support for AI coding assistants. Each vault root directory has an AGENTS.md file that tells AI how to understand your knowledge base structure.

Configuring Claude Code

# In the vault directory
cd ~/my-vault

# Initialize Claude Code (if not already installed)
claude

# Claude Code will automatically read AGENTS.md to understand your note structure

Example AGENTS.md content:

# AGENTS.md - Tolaria Vault Guide

This vault uses the PARA method for organization:

- **Projects/**: Active projects with deadlines
- **Areas/**: Ongoing responsibilities
- **Resources/**: Reference materials
- **Archive/**: Completed or inactive items

## Note Format

All notes are Markdown files with YAML frontmatter:

```yaml
---
title: Note Title
type: note|task|resource
created: YYYY-MM-DD
tags: [tag1, tag2]
---

Common Tasks

• To find recent notes: search by created date in frontmatter
• To find related notes: look for [[wiki-links]]
• To update a project: check projects/ directory

### In Practice: Using AI to Organize Notes

```bash
# Run Claude Code in the vault directory
claude

# Then ask:
# "Summarize all unfinished projects in the projects/ directory"
# "Find all notes containing 'TODO'"
# "Add tags to my Python study notes"

Other Supported AI Tools

• Codex CLI: OpenAI's command-line tool
• Gemini CLI: Google Gemini's command-line interface
• Any LLM: Since notes are plain text, you can process them with any AI tool

Advanced Usage

1. Inbox Workflow: Quick Idea Capture

Tolaria recommends an "Inbox → Organize" workflow:

1. Capture: When you have an idea, quickly create a note in inbox/. Don't worry about categorization.
2. Organize: Review the inbox daily or weekly, and move notes to appropriate folders.

# Example: Quick capture
# Press Cmd/Ctrl + N, enter a title, save as inbox/quick-thought.md

# Regular organization
mv inbox/quick-thought.md projects/project-alpha/
git add .
git commit -m "Organize inbox: move note to project"

2. Web Clipping: Save Web Content

Tolaria provides a browser extension (or Bookmarklet) to save web pages:

// Bookmarklet code (save as a browser bookmark)
javascript:(function(){
  const title = document.title;
  const url = window.location.href;
  const content = document.getSelection().toString() || document.body.innerText;

  const markdown = `---
title: ${title}
type: resource
created: ${new Date().toISOString().split('T')[0]}
source: ${url}
---

# ${title}

${content}
`;

  // Copy to clipboard, then paste into Tolaria
  navigator.clipboard.writeText(markdown);
  alert('Copied to clipboard. Please paste into Tolaria');
})();

3. Template System: Standardize Note Formats

Create templates in the templates/ directory:

# templates/meeting-note.md
---
title: {{title}}
type: meeting
created: {{date}}
attendees: []
---

# {{title}}

**Date:** {{date}}
**Attendees:** 

## Agenda

1. 
2. 

## Discussion Points

## Action Items

- [ ] 

Then copy the template when creating a new note and replace the variables.

4. Integrate with Static Site Generators

Since notes are pure Markdown, you can use an SSG to publish your knowledge base as a website:

# Using MkDocs
pip install mkdocs
mkdocs new my-site
cp -r ~/my-vault/* my-site/docs/
mkdocs serve

# Or using Hugo
hugo new site my-blog
cp -r ~/my-vault/* my-blog/content/
hugo server

5. Multi-Device Sync

Sync across devices via Git:

# Device A (push)
cd ~/my-vault
git add .
git commit -m "Update notes"
git push

# Device B (pull)
cd ~/my-vault
git pull

Tip: If there are conflicts, Git will prompt you to merge manually. For Markdown files, merging is usually straightforward.

Frequently Asked Questions

Q1: What's the difference between Tolaria and Obsidian?

A: The main difference lies in design philosophy: - Obsidian: Feature-rich with a vast plugin ecosystem, but the core is closed-source. - Tolaria: Fully open-source, native Git integration, AI-friendly, and more lightweight.

If you value data sovereignty and open-source transparency, Tolaria is the better choice. If you need a mobile app and a rich community plugin ecosystem, Obsidian might be more suitable.

Q2: Can I migrate from Obsidian to Tolaria?

A: Yes! Since both use pure Markdown files, just:

# Copy Obsidian vault to Tolaria
cp -r ~/obsidian-vault ~/tolaria-vault
cd ~/tolaria-vault
git init
git add .
git commit -m "Migrate from Obsidian"

Then open this folder in Tolaria. The bidirectional link syntax ([[link]]) is also compatible.

Q3: Does Tolaria support mobile devices?

A: Currently, Tolaria is desktop-only (macOS/Windows/Linux). You can access it on mobile via: - Sync with Git, then open with a Markdown editor on your phone (like iA Writer or 1Writer) - Publish the vault as a static website and access it through a browser

Q4: How do I handle image attachments?

A: Create an assets/ folder in your vault to store images:

![Diagram](assets/diagram.png)

# Copy image to assets directory
cp ~/Downloads/diagram.png ~/my-vault/assets/
git add assets/diagram.png
git commit -m "Add diagram"

Q5: How does Tolaria perform? How many notes can it handle?

A: The author uses it to manage 10,000+ notes with smooth daily performance. Performance bottlenecks usually come from: - Git operations (git status slows down with a large number of files) - Full-text search (can be optimized with indexing)

It's recommended to regularly archive old notes to the archive/ directory to keep the number of active notes reasonable.

Summary

Tolaria is a knowledge base tool designed for developers. Its core values are:

1. Data Sovereignty: Pure Markdown files, zero lock-in
2. Version Control: Native Git integration, natural history tracking
3. AI-Friendly: Native support for mainstream AI coding assistants
4. Open Source & Free: Fully transparent, no hidden costs
5. Cross-Platform: macOS / Windows / Linux

Ideal for: - ✅ Developers and technical writers - ✅ Knowledge workers who value data sovereignty - ✅ Teams already using Git - ✅ Users who want AI-assisted knowledge management

Not ideal for: - ❌ Users who need a mobile app - ❌ Users who prefer rich media embedding (videos, interactive charts) - ❌ Non-technical users who don't want to deal with Git

Resource Links: - Tolaria GitHub Repository - Download Page - Starter Vault Template - Author Luca's X Account

If you found this article helpful, feel free to share it with more developers!