Main Features of Tolaria: Local-First Markdown Knowledge Base

Tolaria is a local-first, markdown-driven knowledge base that stores notes as plain .md files on disk while providing a rich BlockNote WYSIWYG editor, integrated AI assistance, native Git version control, and conflict-aware file synchronization—all packaged as a native desktop application using Tauri.

Tolaria is an open-source knowledge management application from refactoringhq/tolaria that bridges the gap between plain-text durability and modern UI richness. Unlike cloud-locked note-taking apps, Tolaria treats the filesystem as the single source of truth, ensuring your data remains portable and future-proof. This article explores the core Tolaria features implemented across the React/TypeScript frontend and Tauri native backend, with direct references to the source code implementing each capability.

Durable Markdown-First Architecture

Every note in Tolaria exists as a plain .md file on your local disk, eliminating proprietary databases and ensuring your data remains accessible outside the application. The vault management system handles filesystem operations through src/utils/vaultListStore.ts, which maintains the list of vault entries and watches for changes, while src/utils/vaultMetadataNormalization.ts parses and normalizes YAML frontmatter.

To open a vault programmatically:

import { openVault } from "src/utils/vaultListStore";

await openVault("/Users/alice/Laputa");

The note creation utility in src/utils/noteTitle.ts handles file naming and initialization:

import { createNote } from "src/utils/noteTitle";

await createNote({
  title: "Meeting notes",
  parentPath: "Projects/2024",
  type: "note"
});

This architecture guarantees that your notes are never locked behind a vendor-specific format, allowing you to use external editors or version control tools without export friction.

Rich BlockNote Editing Experience

Tolaria provides a WYSIWYG editing interface built on BlockNote, supporting headings, code blocks, tables, and drag-reorderable blocks while maintaining pure Markdown underneath. The main editor UI resides in src/components/Editor.tsx, with specialized handling for wiki-style internal links implemented in src/components/InlineWikilinkInput.tsx.

The editor renders Markdown content as interactive blocks, bridging the gap between raw text editing and visual document composition without sacrificing file portability.

AI Assistance with Multi-Agent Support

The application includes a built-in AI panel supporting multiple agents including Claude, OpenCode, Pi, and Gemini, with configurable permission modes for safe or power-user operation. The UI layer lives in src/components/AiPanel.tsx, while the abstraction layer for different AI providers is implemented in src/utils/ai-agent.ts.

To invoke an AI agent programmatically:

import { askAi } from "src/utils/ai-chat";

const response = await askAi({
  agentId: "claude",
  prompt: "Summarize the current note."
});

This multi-agent architecture, described in docs/adr/0108-direct-model-ai-targets.md, allows users to select specific AI capabilities for different tasks while maintaining consistent UI patterns across providers.

Native Git Version Control

Tolaria integrates Git directly into the desktop interface, allowing users to commit, push, and pull changes without leaving the application. The commit interface is implemented in src/components/CommitDialog.tsx, while merge conflicts are handled through the visual resolver in src/components/ConflictResolverModal.tsx.

To trigger a commit from a custom component:

<CommitDialog
  vaultPath={vault.path}
  onCommit={(msg) => gitCommit(vault.path, msg)}
/>

The Git integration works seamlessly with the Markdown file structure, treating your knowledge base as a standard repository that can sync with remote hosts like GitHub or GitLab.

Media Preview and File Handling

The application provides native-quality preview capabilities for images and PDFs without requiring external viewers. Image previews are handled by src/components/ImageLightbox.tsx, which supports thumbnails and full-screen viewing modes, while PDF preview logic resides in src/components/FilePreview.test.tsx.

This allows users to embed and reference media assets within their Markdown notes while maintaining a consistent reading experience.

Structured Property System

Tolaria supports structured metadata through a flexible property system that includes tags, custom color palettes, and status dropdowns. Type definitions live in src/utils/propertyTypes.ts, while the inline editing interface is rendered by src/components/DynamicPropertiesPanel.tsx.

To render a property panel in a custom component:

<DynamicPropertiesPanel
  entry={currentEntry}
  onChange={(newProps) => updateProperties(currentEntry.id, newProps)}
/>

This system enables database-like querying and filtering of plain Markdown files through structured frontmatter.

Advanced Search and Filtering

The application provides full-text search across the entire vault, complemented by a visual filter builder for tags, types, and status values. The filter UI is implemented in src/components/FilterBuilder.tsx, with the filtering engine residing in src/utils/viewFilters.ts.

Users can save filtered views for quick access, effectively creating dynamic smart folders based on note metadata without moving files from their original locations.

Conflict-Aware File Synchronization

Tolaria monitors the filesystem for external changes—such as edits from another application or Git pull operations—and refreshes the UI safely without data loss. This logic is centralized in src/utils/pulledVaultRefresh.ts, which detects conflicts between disk state and application state.

This ensures that Tolaria remains compatible with external editing workflows, including terminal-based Git operations or third-party Markdown editors.

Native Desktop Integration with Tauri

Packaged as a native application using Tauri, Tolaria leverages OS-level menus, window controls, and custom asset protocols while maintaining a web-based React/TypeScript frontend. Cross-runtime command definitions are stored in src/shared/appCommandManifest.json, enabling consistent behavior across operating systems.

The Tauri architecture provides native performance characteristics—including fast startup and low memory usage—while the web frontend ensures rapid feature iteration and a rich plugin ecosystem.

Summary

• Filesystem-first storage: Notes exist as plain .md files managed by src/utils/vaultListStore.ts, ensuring portability and preventing vendor lock-in.
• Rich BlockNote editing: The WYSIWYG interface in src/components/Editor.tsx provides drag-reorderable blocks while maintaining Markdown purity.
• Multi-agent AI support: Integrated assistance through src/components/AiPanel.tsx with abstractions in src/utils/ai-agent.ts for Claude, OpenCode, Pi, and Gemini.
• Native Git integration: Version control UI in src/components/CommitDialog.tsx and conflict resolution in src/components/ConflictResolverModal.tsx.
• Structured metadata: Property types defined in src/utils/propertyTypes.ts enable filtering and saved views via src/components/FilterBuilder.tsx.
• Conflict-aware synchronization: External change detection handled by src/utils/pulledVaultRefresh.ts for safe multi-app workflows.

Frequently Asked Questions

How does Tolaria store notes compared to cloud-based applications?

Tolaria stores every note as a plain .md file on your local disk, managed through src/utils/vaultListStore.ts, rather than in a proprietary database or remote server. This local-first approach means your data remains readable by any text editor and can be synchronized using standard tools like Git or Dropbox.

Can I use Git for version control within Tolaria?

Yes, Tolaria includes native Git integration through src/components/CommitDialog.tsx for creating commits and src/components/ConflictResolverModal.tsx for resolving merge conflicts. The application treats your vault as a standard Git repository, allowing you to track changes, revert edits, and sync with remote hosts directly from the interface.

What AI models are supported by the Tolaria AI panel?

According to src/utils/ai-agent.ts and the UI in src/components/AiPanel.tsx, Tolaria supports multiple AI agents including Claude, OpenCode, Pi, and Gemini. The architecture allows switching between providers while maintaining consistent permission modes and UI patterns as documented in docs/adr/0108-direct-model-ai-targets.md.

Is Tolaria extensible for adding custom features?

Yes, Tolaria follows an ADR-driven design process with architecture decisions recorded in docs/adr/, such as 0108-direct-model-ai-targets.md which describes the extensible AI target system. The React/TypeScript frontend and command manifest in src/shared/appCommandManifest.json provide clean extension points for new functionality without breaking existing contracts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}