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

> Explore Tolaria's limitations: filesystem-only, 20-result search cap, AI context truncation, single-note editing, and mandatory Git. Understand the constraints before adopting this Markdown knowledge base.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: deep-dive
- Published: 2026-05-04

---

**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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/vault/cache.rs))

## Local-Only Operation and Platform Limits

As stated in [`README.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/ai-context.ts):

```typescript
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`](https://github.com/refactoringhq/tolaria/blob/main/src/hooks/useNoteSearch.ts) defaults to a maximum of 20 results unless explicitly overridden:

```typescript
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`](https://github.com/refactoringhq/tolaria/blob/main/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:

```typescript
// 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`](https://github.com/refactoringhq/tolaria/blob/main/src/hooks/useZoom.ts) clamps values between 0.8× and 1.5×:

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

```

### Component Library Restrictions

Per [`AGENTS.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md) and [`mcp-server/vault.js`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/vault/cache.rs).