Common Use Cases for Tolaria: A Git-Backed Markdown Knowledge Base

Tolaria serves as a cross-platform desktop application for managing markdown-based knowledge bases, enabling personal note-taking, team documentation, and AI agent memory systems through a git-tracked vault architecture.

Tolaria is an open-source desktop application built with Tauri, React, and Rust that transforms local markdown files into a powerful knowledge management system. The application, maintained at refactoringhq/tolaria, operates entirely on your filesystem using a git-tracked vault structure. This design gives you complete ownership of your data while supporting both human workflows and AI agent integrations through a Model Context Protocol (MCP) server.

Personal Knowledge Management (Second Brain)

The primary common use case for Tolaria is maintaining a personal "second brain" for all your notes, journal entries, and project documentation. Because the vault is simply a directory of markdown files on your local filesystem, you maintain full control without cloud service dependencies. As noted in the project README, this approach ensures your knowledge base remains searchable, portable, and completely independent of any specific software vendor.

Company Documentation and Git-First Workflows

Teams leverage Tolaria to store internal documentation, policies, and technical specifications alongside their code repositories. The application's git-first architecture means every change is automatically committed to version control, providing instant diffs, history tracking, and code review workflows. According to the architecture documentation in docs/ARCHITECTURE.md, Tolaria automatically initializes a git repository for new vaults, making it trivial to push documentation to remote servers or integrate with existing CI/CD pipelines.

AI Agent Memory and Procedure Storage

Tolaria functions as a long-term memory system for AI assistants through its built-in MCP server running on port 9710. Agents such as Claude, Codex, Open-Code, and Gemini can read from and write to your vault using standardized tool calls. This enables AI systems to maintain context across sessions, edit notes programmatically, and execute tool calls without exposing sensitive API keys to external services.

The MCP server exposes specific tools including search_notes, read_note, and append_to_note defined in mcp-server/vault.js. These capabilities transform your markdown vault into an active workspace where both humans and AI agents collaborate on documentation.

Large-Scale Knowledge Graphs

Beyond simple note storage, Tolaria treats your vault as a rich knowledge graph where notes function as nodes with typed frontmatter, backlinks, and relationships. The cache layer in src-tauri/src/vault/cache.rs ensures that even large vaults with thousands of interconnected notes remain responsive at startup. This graph structure supports both manual navigation through backlinks and automated traversal by AI agents seeking specific information.

Technical Implementation Code Examples

Creating new notes in Tolaria follows a disk-first architecture that writes to the filesystem before updating the UI state. The following React component demonstrates the pattern using shadcn/ui components and a custom hook:

import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";
import { useCreateNote } from "@/hooks/useCreateNote";

function NewNoteForm() {
  const createNote = useCreateNote();
  const [title, setTitle] = useState("");

  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        createNote.mutate({ title, type: "Idea" });
        setTitle("");
      }}
    >
      <Input
        placeholder="Note title"
        value={title}
        onChange={e => setTitle(e.target.value)}
      />
      <Button type="submit">Create</Button>
    </form>
  );
}

Relevant source files: src/components/ui/input.tsx, src/components/ui/button.tsx, and src/hooks/useCreateNote.ts.

Searching Notes via MCP

External tools and AI agents can search the vault through WebSocket connections to the MCP server defined in src-tauri/src/mcp.rs:

const ws = new WebSocket("ws://localhost:9710");
ws.onopen = () => {
  ws.send(
    JSON.stringify({
      id: "req-1",
      tool: "search_notes",
      args: { query: "meeting", limit: 10 },
    })
  );
};

ws.onmessage = event => {
  const resp = JSON.parse(event.data);
  console.log("Search results:", resp.result);
};

This implementation connects to the search_notes tool defined in mcp-server/vault.js, enabling programmatic access to your knowledge base.

AI Agent Integration

The following pattern illustrates how AI agents interact with notes using the MCP bridge, specifically calling read_note and append_to_note as implemented in the Rust backend and JavaScript tool handlers:

await fetch("http://localhost:9710", {
  method: "POST",
  body: JSON.stringify({
    id: "a1",
    tool: "read_note",
    args: { path: "projects/launch.md" },
  }),
});

await fetch("http://localhost:9710", {
  method: "POST",
  body: JSON.stringify({
    id: "a2",
    tool: "append_to_note",
    args: {
      path: "projects/launch.md",
      text: "\n\n## Summary\nAI-generated recap of meeting notes.",

    },
  }),
});

These operations are handled by the Rust coordination layer in src-tauri/src/ai_agents.rs and the concrete implementations in mcp-server/vault.js.

Summary

• Tolaria provides a filesystem-first markdown editor built with Tauri, React, and Rust for managing git-tracked knowledge vaults.
• Primary use cases include personal second brains, company documentation workflows, AI agent memory systems, and large-scale knowledge graphs.
• Zero lock-in architecture stores all data as plain markdown files with frontmatter, enabling migration to any other tool at any time.
• AI integration occurs through a local MCP server (port 9710) exposing tools like search_notes and append_to_note defined in mcp-server/vault.js.
• Git-first workflow automatically versions all changes, supporting branch-based editing and remote collaboration through standard git operations.

Frequently Asked Questions

How does Tolaria differ from Obsidian or other markdown editors?

Unlike Obsidian, Tolaria is fully open-source and built explicitly around a git-first workflow where every change is automatically committed to version control. The application also features a built-in MCP server for AI agent integration, as implemented in src-tauri/src/mcp.rs, allowing programmatic access to your vault that most traditional editors do not provide.

Can multiple team members collaborate on a Tolaria vault?

Yes. Since each Tolaria vault is a standard git repository, teams can collaborate using familiar git workflows including branching, pull requests, and merge conflict resolution. The application detects remote changes and can sync with central repositories while maintaining the local cache layer for performance.

What types of AI agents work with Tolaria?

Any AI agent supporting the Model Context Protocol (MCP) can connect to Tolaria's local server on port 9710 to read and write notes. This includes Claude Desktop, Open-Code, Codex CLI, and custom agents built with the MCP SDK. The integration allows agents to maintain long-term memory across sessions without cloud API dependencies.

Is Tolaria suitable for vaults containing thousands of notes?

Yes. The architecture includes a sophisticated caching system in src-tauri/src/vault/cache.rs that indexes note metadata, backlinks, and relationships for fast startup and search performance. The disk-first data model ensures the UI remains responsive even as the knowledge graph scales to thousands of interconnected markdown files.

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