Tolaria's Limitations: Understanding the Constraints of a Markdown-First Knowledge Base

Tolaria imposes specific constraints including a filesystem-only data model with no cloud sync, a 20-result search cap, AI context truncation at ~108k tokens, single-note-per-window editing, and mandatory Git for version control features.

Tolaria is a desktop-first markdown knowledge-base manager built with Tauri and React. While it offers a fast, offline-first experience, understanding Tolaria's limitations is crucial for evaluating whether it fits your workflow. This guide examines the hard boundaries defined in the source code, from storage architecture to UI constraints.

Filesystem-Only Architecture Constraints

Tolaria stores all notes as plain .md files with YAML front-matter and never uses a proprietary database. According to docs/ARCHITECTURE.md, "the vault is a folder of plain markdown files. The app never owns the data … the cache, React state, and any in‑memory representation are always derived from the filesystem."

This design choice means:

• No native binary file management: Large files or non-markdown formats require external tooling
• Cache-dependent performance: The fast startup cache lives under ~/.laputa/cache. If corrupted, Tolaria falls back to a full disk scan, which slows significantly for vaults exceeding 10,000 notes (as implemented in src-tauri/src/vault/cache.rs)

Local-Only Operation and Platform Limits

As stated in README.md, Tolaria maintains "Offline‑first, zero lock‑in – No accounts, no subscriptions, no cloud dependencies." All vault operations happen on the local disk; remote collaboration requires external Git tools.

Platform support has specific constraints:

• Linux dependencies: Requires WebKit2GTK 4.1 and GTK 3, with potential rendering issues on Wayland
• No built-in cloud sync: Unlike SaaS knowledge bases, Tolaria has no native synchronization service

AI and Search Limitations

Tolaria's AI integration and search functionality operate within strict boundaries.

AI Context Truncation

When invoking AI agents, Tolaria truncates content to stay within token limits. As documented in docs/adr/0027-dual-ai-architecture.md, the default token budget uses "60% of 180k context limit (~108k tokens max)". The truncation logic resides in src/utils/ai-context.ts:

import { truncateActiveNote } from '@/utils/ai-context';
const truncated = truncateActiveNote(activeNote.body, { maxTokens: 108_000 });

Large notes exceeding this threshold lose content in the AI prompt window.

Search Result Cap

The useNoteSearch hook in src/hooks/useNoteSearch.ts defaults to a maximum of 20 results unless explicitly overridden:

import { useNoteSearch } from '@/hooks/useNoteSearch';
const results = useNoteSearch(entries, 'project roadmap'); // returns ≤20 items

The UI also caps results shown in the quick-open palette.

UI and Editor Constraints

Tolaria enforces specific interaction models that limit flexibility.

Single-Note Window Model

Tolaria does not support tabs. As docs/ARCHITECTURE.md states: "Single note open at a time (no tabs – see ADR‑0003)." Opening a second note creates a new Tauri window rather than a tab:

// Opening a second note spawns a new window (no tab)
await invoke('open_note_in_new_window', { path: 'notes/meeting.md' });
// → Tauri creates a secondary WebviewWindow (see src/NoteWindow.tsx)

Editor Zoom Limits

The zoom functionality in src/hooks/useZoom.ts clamps values between 0.8× and 1.5×:

import { useZoom } from '@/hooks/useZoom';
const [zoom, setZoom] = useZoom();   // zoom ∈ [0.8, 1.5]

Component Library Restrictions

Per AGENTS.md, "Always use shadcn/ui components. Never use raw HTML form elements." This constraint ensures visual consistency but prevents custom form elements or rapid prototyping of bespoke controls.

Mandatory Git Dependencies

Version control features depend entirely on Git. According to docs/ARCHITECTURE.md: "If a vault is not yet a git repo, Tolaria shows a dismissible Git setup dialog and a persistent Git disabled status‑bar warning." Without Git, the Pulse view, change history, and conflict resolution panels remain disabled.

MCP-Driven AI Tooling Constraints

AI agents communicate via the Model Context Protocol (MCP) server with a fixed tool surface of 14 tools. Only agents exposing compatible CLIs (Claude Code, Codex, OpenCode, Pi, Gemini) are supported, as detailed in docs/ARCHITECTURE.md and mcp-server/vault.js. Other models require additional adapters.

Summary

• Tolaria's limitations stem from its filesystem-first architecture: no proprietary database, no cloud sync, and Git-dependent features
• Search caps at 20 results by default (useNoteSearch.ts), while AI context truncates at ~108k tokens
• Single-note-per-window editing with zoom clamped between 0.8× and 1.5×
• Platform constraints on Linux require WebKit2GTK 4.1 and GTK 3
• UI development restricted to shadcn/ui components; custom HTML elements prohibited
• Cache corruption triggers slow full-disk scans for large vaults

Frequently Asked Questions

Can Tolaria handle large binary files or non-markdown formats?

No. Tolaria's vault consists exclusively of plain markdown files with YAML front-matter. Binary content and other formats require external management tools, as the app cannot stream large files or manage non-text data within its core architecture.

Why does Tolaria limit AI context to 108,000 tokens?

This limitation prevents exceeding the provider's context window while reserving tokens for system instructions and tool definitions. The 60% budget of the 180k limit ensures reliable operation across supported AI agents using the Model Context Protocol.

Does Tolaria support multi-tab editing?

No. Tolaria allows only one note per window. Opening additional notes creates separate Tauri windows rather than browser-style tabs, simplifying state management but requiring window management for simultaneous editing.

What happens if the Tolaria cache becomes corrupted?

Tolaria automatically falls back to a full filesystem scan, rebuilding the in-memory representation from scratch. This process becomes noticeably slow for vaults containing more than 10,000 notes, as documented in the cache implementation at src-tauri/src/vault/cache.rs.

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