mech.app
Dev Tools

Tolaria: Git-First Knowledge Base as Agent Context Store

How Tolaria's markdown-in-git architecture turns local note vaults into portable, versionable context stores that agents can read without vendor depende...

Source: github.com
Tolaria: Git-First Knowledge Base as Agent Context Store

Tolaria is a desktop knowledge base that stores notes as plain markdown files inside git repositories. No database. No proprietary format. No cloud dependency. Every vault is a git repo. Every note is a markdown file with YAML frontmatter. The architecture matters because it turns local note collections into portable, versionable context stores that AI agents can consume directly.

The project recently appeared on GitHub’s TypeScript trending list. The creator runs a 10,000+ note workspace for personal and company knowledge. The design explicitly targets AI context use cases: organizing company docs for agents, storing assistant memory and procedures, and feeding context to coding tools like Claude Code or Cursor.

Why Files-First Matters for Agents

Most knowledge bases lock data in SQLite or proprietary formats. Exporting to markdown is a separate step. Tolaria inverts this: the source of truth is markdown files on disk. Agents read them directly. No export, no sync layer, no API rate limits.

Each note is a file. Relationships between notes are expressed in YAML frontmatter and wikilink syntax (double-bracket links like [[note-name]] that reference other notes by filename). An agent can parse the vault by walking the file tree and reading frontmatter. No database queries, no schema migrations, no vendor SDK.

Key properties:

  • Portability: Copy the folder, you have the entire vault. No database dump required.
  • Versionability: Every change is a git commit. Agents can diff context over time.
  • Tooling compatibility: Standard markdown parsers, grep, ripgrep, and any editor work out of the box.
  • No vendor dependency: Stop using Tolaria, keep using the files. The data format outlives the app.

Git as Sync and Version Layer

Every Tolaria vault is a git repository. This gives you:

  • Full history: Every edit is versioned. Agents can retrieve past context states.
  • Remote sync: Push to GitHub, GitLab, or any git remote. Multi-device access without a proprietary sync service.
  • Branch workflows: Experiment with context changes in branches before merging.
  • Conflict resolution: Git handles merge conflicts. You resolve them in text, not in a proprietary UI.

Trade-off: Git is not designed for high-frequency writes. If an agent appends to a note every second, you will accumulate thousands of commits. The vault will bloat. You need a commit batching strategy or a separate append log that periodically flushes to the vault.

Conflict handling: If two devices edit the same note simultaneously, git will flag a conflict. Agents must handle this. Options include:

  • Last-write-wins: Overwrite the conflicted file. Simple, lossy.
  • Merge strategy: Parse both versions, merge content programmatically.
  • Manual resolution: Surface the conflict to a human.

Agent Integration Patterns

Three ways an agent can integrate with a Tolaria vault:

PatternMechanismProsCons
Direct file accessAgent reads/writes markdown files in the vault directoryZero latency, no server overhead, full git historyRequires local file access, agent must handle git operations
MCP serverAgent calls MCP tools exposed by a server layer that wraps the vaultStandard protocol, remote access possible, abstracts git operationsAdds server dependency, MCP spec still evolving, latency overhead
API layerREST or GraphQL API over the vaultLanguage-agnostic, supports auth and rate limitingMost complex, requires server infrastructure, breaks offline-first principle

Direct file access is the most straightforward. An agent running on the same machine can read the vault directory, parse markdown, and write new notes. The agent must commit changes to git. Example flow in TypeScript:

import fs from 'fs/promises';
import { execSync } from 'child_process';
import yaml from 'js-yaml';

async function readNote(vaultPath: string, notePath: string) {
  const content = await fs.readFile(`${vaultPath}/${notePath}`, 'utf-8');
  const [, frontmatterRaw, body] = content.match(/^---\n(.*?)\n---\n(.*)$/s) || [];
  const frontmatter = yaml.load(frontmatterRaw);
  return { frontmatter, body };
}

async function writeNote(vaultPath: string, notePath: string, frontmatter: any, body: string) {
  const content = `---\n${yaml.dump(frontmatter)}\n---\n${body}`;
  await fs.writeFile(`${vaultPath}/${notePath}`, content);
  execSync(`cd ${vaultPath} && git add . && git commit -m "Agent: updated ${notePath}"`);
}

// Agent reads existing note
const note = await readNote('vault', 'projects/mech-app.md');
console.log(note.frontmatter.tags);

// Agent writes a new note
await writeNote('vault', 'logs/2025-06-08-deploy.md', {
  title: 'Deploy log',
  date: '2025-06-08',
  related: ['[[infra-setup]]', '[[ci-pipeline]]']
}, 'Deployed mech.app v2.3.0 to production.');

MCP server is the standard integration path for Claude and other MCP-compatible agents. An agent integrating with Tolaria via MCP would call tools like:

  • list_notes(tag: string): Return all notes with a given tag.
  • read_note(path: string): Return note content and frontmatter.
  • write_note(path: string, content: string): Create or update a note.
  • search_vault(query: string): Full-text search across the vault.

The MCP server would handle git commits internally. The agent calls tools, the server writes files and commits. This abstracts git complexity but adds a server process.

API layer is overkill for local use but necessary for remote agents. A REST API over the vault enables web-based agents or multi-user scenarios. You lose offline-first guarantees and introduce auth, rate limiting, and deployment complexity.

Frontmatter as Structured Context

Tolaria notes use YAML frontmatter for metadata. Example:

---
title: "Deploy mech.app to production"
tags: [deployment, infrastructure]
status: complete
date: 2025-06-08
related: 
  - "[[infra-setup]]"
  - "[[ci-pipeline]]"
---

Deployed mech.app v2.3.0 to production. No errors. Monitoring dashboards green.

Agents parse frontmatter to extract:

  • Tags: Group related notes. An agent can fetch all notes tagged deployment.
  • Status: Track task state. An agent can filter for status: in-progress.
  • Relationships: Wikilinks in related fields form a graph. An agent can traverse dependencies.
  • Dates: Time-series analysis of context changes.

Frontmatter is not enforced by Tolaria. You define your own schema. This flexibility is useful but requires discipline. If different notes use inconsistent tag names or date formats, agents must normalize.

State Management and Observability

Tolaria itself has no state beyond the file system and git history. State management is the agent’s responsibility.

Agent state options:

  • Stateless: Agent reads vault on every invocation. Simple, slow for large vaults.
  • In-memory cache: Agent loads vault into memory, watches file changes. Fast, requires file watcher.
  • Separate state store: Agent maintains its own database of vault metadata. Complex, introduces sync issues.

Observability: Git history is the audit log. Every agent action that modifies the vault creates a commit. You can inspect:

  • Who changed what: Git blame shows which agent or user modified a note.
  • When context changed: Git log shows the timeline of edits.
  • What was the context at time T: Git checkout a past commit to see the vault state.

Failure modes:

  • Uncommitted changes: Agent crashes before committing. Changes are lost unless you have a pre-commit hook or staging area.
  • Merge conflicts: Two agents edit the same note. Git flags a conflict. You need a resolution strategy.
  • Vault corruption: Malformed YAML or broken wikilinks. Agents must validate before writing.

Security Boundaries

Tolaria vaults are local files. Security depends on file system permissions and git remote access.

Local access: If an agent has file system access, it can read and write the entire vault. No row-level security, no access control lists. You must trust the agent or avoid running it.

Remote access: If you push the vault to a git remote, anyone with repo access can clone it. Use private repos or encrypted remotes. Git-crypt or git-secret can encrypt sensitive notes at rest.

Agent sandboxing: If you run untrusted agents, sandbox file access. Use Docker volumes, chroot, or file system ACLs to limit which notes an agent can touch.

Secrets in notes: Do not store API keys or credentials in plaintext notes. Use environment variables or a separate secrets manager. If you must store secrets, encrypt them in frontmatter or use a git-crypt filter.

Deployment Shape

Tolaria is a desktop app. Agents integrate by:

  1. Running on the same machine: Agent reads vault files directly.
  2. Running remotely: Agent clones the vault from a git remote, operates on a local copy, pushes changes back.

Multi-device workflow:

  1. Device A: Tolaria app + agent. Agent writes notes, commits to git.
  2. Device A: Push to remote (GitHub, GitLab).
  3. Device B: Pull from remote. Tolaria app shows updated notes.
  4. Device B: Agent reads new notes, writes more notes, commits, pushes.

Conflict scenario:

  1. Device A and Device B both edit project-plan.md offline.
  2. Device A pushes first.
  3. Device B pulls, git flags a conflict.
  4. Device B resolves conflict (manually or via agent), commits, pushes.

Latency: Git push/pull adds latency. For real-time collaboration, git is not ideal. For async agent workflows, it works fine.

When to Use Tolaria for Agent Context

Use Tolaria when:

  • You want portable, versionable context that outlives any app.
  • Your agents need to read and write structured notes without vendor dependency.
  • You already use git for version control and want to extend it to knowledge management.
  • You need offline-first context storage with no cloud dependency.
  • You want to inspect agent actions via git history.

Avoid Tolaria when:

  • You need real-time collaboration with sub-second sync. Git is too slow.
  • You need fine-grained access control. File system permissions are coarse.
  • You need high-frequency writes (thousands of commits per hour). Git will bloat.
  • You need a query language more complex than grep. A database is better.
  • You need a hosted service. Tolaria is local-first, self-hosted only.

Technical Verdict

Tolaria’s git-first, files-first architecture solves the vendor dependency problem for agent context stores. Your notes are markdown files. Your version history is git commits. Your sync layer is any git remote. No proprietary format, no vendor API, no export step.

The trade-off is that git is not a database. You lose query optimization, fine-grained access control, and real-time sync. You gain portability, auditability, and tooling compatibility. For agents that need persistent, versionable context without cloud dependencies, this is a strong fit. For agents that need high-frequency writes or complex queries, look elsewhere.

The MCP integration path is the cleanest for modern agents. Direct file access works for local agents with git knowledge. API layers are possible but break the offline-first principle.

If you are building a coding assistant that needs to remember project context across sessions, Tolaria gives you a file-based memory layer that survives app restarts and works offline. If you are building a multi-agent system where agents need to share structured knowledge, Tolaria provides a git-backed coordination layer with full audit trails. The extensibility comes from standard file formats and git tooling that agents can leverage directly.