Tolaria

Type: ../types/agent-memory-system-review.md · Status: current · Tags: related-systems

Tolaria is a Mac and Linux desktop app from RefactoringHQ for operating markdown knowledge bases as local, git-backed vaults. Its strongest relevance to commonplace is not trace-derived learning but the productized authoring and activation layer around local files: Tolaria makes remembered material discoverable, inspectable, and agent-accessible through a human desktop UI, git workflows, managed guidance, context snapshots, and MCP tools.

Repository: https://github.com/refactoringhq/tolaria

Reviewed commit: https://github.com/refactoringhq/tolaria/commit/151e993ab7dd4f86e7dcb9a32ec0f4deb5ae2565

Core Ideas

Filesystem and git are the authority boundary. Tolaria's central memory bet is that user-authored markdown files, not an app database, are the durable substrate. The README frames files-first, git-first, offline-first operation as product principles, and the architecture doc makes the filesystem the winning representation whenever cache or React state diverges (README.md, docs/ARCHITECTURE.md). The Rust scanner implements that stance by parsing markdown and editable non-markdown files into VaultEntry records while keeping hidden app directories out of normal scans (src-tauri/src/vault/mod.rs). Git is not just backup: commit, pull, push, clone, remote state, conflict state, and Pulse activity all operate through the user's local git tooling rather than a hosted Tolaria sync service (docs/ARCHITECTURE.md, src-tauri/src/git/commit.rs).

Memory roles exist as conventions and files, not as hard contracts. Tolaria distinguishes several artifact roles: ordinary notes, type documents in type/, saved views in views/*.yml, root AGENTS.md guidance, a CLAUDE.md shim, git history, cache files outside the vault, and transient rename transaction manifests. These roles are real enough for the UI and backend to behave differently, but most are governed by conventions rather than validation schemas. Type documents can carry icon, color, ordering, default view, visibility, sort, and templates; they are intentionally "lenses, not schemas" (docs/ABSTRACTIONS.md, README.md). This makes Tolaria strong at low-friction adoption and weak at enforcing document quality obligations.

Relationship memory is dynamic and UI-legible. Tolaria treats any non-system frontmatter field containing wikilinks as a relationship, with standard fields such as belongs_to, related_to, and has but no closed relation vocabulary. The parser extracts relationship maps generically and separately extracts scalar properties; it also adds a synthetic Type relationship for typed entries so types become navigable graph nodes (src-tauri/src/vault/frontmatter.rs, src-tauri/src/vault/mod.rs). The product surface converts those relationships into Neighborhood mode: outgoing groups, inverse/backlink groups, duplicate-preserving sections, and entity pivots (docs/ARCHITECTURE.md, docs/ABSTRACTIONS.md). The remembered connection can change what a human or agent reads next, but it does not encode what inference the connection authorizes.

Consumer surfaces are intentionally plural. Tolaria serves humans through a desktop UI, agents through an AI panel and MCP tools, git users through ordinary repositories, and power users through raw files. The AI panel builds a structured snapshot from the active note, visible/open context, vault types, note list, and explicitly referenced notes, while the Rust layer spawns Claude Code or Codex CLI with Tolaria's MCP server configured for the vault (src/utils/ai-context.ts, src-tauri/src/ai_agents.rs). External assistants can register Tolaria's MCP server explicitly in Claude Code or Cursor config files; the registration is additive and reversible (src-tauri/src/mcp.rs, docs/ARCHITECTURE.md).

Activation is an orientation layer, not a learning loop. Tolaria can load behavior-relevant context before an agent answers: the active-note snapshot tells the agent what the user is looking at, the MCP tools let it search/read the vault, and AGENTS.md tells agents the vault conventions. This is stronger than question-answer retrieval bolted onto a note store. But the activation logic is still local and situational: it does not mine prior sessions into new rules, score memory usefulness, or promote observations into stronger artifacts. The checked-in stdio MCP server exposes six tools: search, vault context, note read, UI open, UI highlight, and refresh (mcp-server/index.js). The WebSocket bridge adds read/search/context and UI actions but still no durable create/edit/delete/link tool handlers (mcp-server/ws-bridge.js). Write authority remains mostly with the app's Tauri commands and the agent's native filesystem tools, despite the architecture doc's larger 14-tool table (docs/ARCHITECTURE.md).

Derived views are source-backed enough to be inspected and repaired. Tolaria uses generated and compiled surfaces, but it keeps their authority relationship understandable. The cache in ~/.laputa/cache/<hash>.json is disposable, versioned, keyed by vault path and git HEAD, incrementally updated from git diff/status, and replaced with a lock plus temp-file-and-rename path (src-tauri/src/vault/cache.rs, docs/ARCHITECTURE.md). Saved views are not hidden app state: views/*.yml files define nested all/any filters, sort, and displayed list properties, then evaluate against built-in fields, custom properties, body content, dates, and relationships (src-tauri/src/vault/views.rs). Rename transactions are staged under .tolaria-rename-txn/, recovered on future scans, and tied to backlink rewrite attempts rather than silent path mutation (src-tauri/src/vault/rename.rs, src-tauri/src/vault/rename_transaction.rs).

Authority is mostly local, with guardrails around app-mediated writes. The strongest trust mechanisms are inspectability, git history, path boundaries, and preservation of user-customized guidance. Command-layer file operations canonicalize the active vault root and reject path escapes before reads, saves, deletes, view edits, folder mutations, and image writes reach the backend (src-tauri/src/commands/vault/boundary.rs, docs/ABSTRACTIONS.md). Managed guidance has explicit states: missing, broken, managed, or custom. Tolaria can restore missing/broken AGENTS.md and CLAUDE.md files while avoiding overwrites of custom guidance (src-tauri/src/vault/config_seed.rs). There is no comparable authority model for deciding whether a memory is good, promoted, stale, or behavior-changing.

Comparison with Our System

Lens axis Tolaria Commonplace
Creation and import Human/app/agent writes into a markdown vault; clone/open/create flows preserve ordinary files Agent and maintainer write typed library artifacts, workshop drafts, snapshots, reviews, ADRs, and instructions
Evidence and trust Git history, plain files, source-readable views, path boundaries, managed guidance states Frontmatter contracts, validation, semantic review, explicit source snapshots, citation norms, review state
Artifact contracts Notes, type docs, views, guidance, cache, git activity, rename transactions as conventions Path-valued type specs define required sections, metadata, validation, and role-specific writing contracts
Consumer surfaces Desktop UI, raw files, git, AI panel, MCP read/search/UI tools Shell, rg, generated indexes, skills, validators, review workflows, assistant guidance files
Activation Active-note context snapshot, vault search/read tools, AGENTS guidance, UI open/highlight Agent loads repo guidance, collection conventions, type specs, indexes, and specific notes on demand
Promotion/codification Human or agent can edit files, but no implemented trace-to-rule or note-to-skill promotion loop Explicit promotion from workshop/sources into notes, instructions, ADRs, scripts, validators, and skills
Compiled views/lifecycle Cache and saved views are rebuildable or file-backed; guidance restore preserves custom files Generated indexes, reports, validation outputs, review bundles, and workshop closure conventions
Authority/evaluation Local filesystem owner and git decide persistence; app guards unsafe paths and managed file overwrites Type contracts, validation scripts, review gates, collection rules, and maintainer decisions decide trust
Adoption affordances Strong: native desktop, standard markdown/git, existing CLI agents, no hosted dependency Strong for agent-operated repos; weaker as a human desktop cockpit

Tolaria is best read less as a deficient memory learner and more as a strong adoption layer around an existing file substrate. It does not learn from traces, but it lowers the cost of creating, inspecting, navigating, and activating human-authored memory. That matters because many agent-memory systems over-invest in storage/retrieval mechanisms while leaving the daily authoring environment awkward.

The sharpest divergence is artifact authority. In commonplace, a type is a contract: an agent-memory-system review has freshness metadata, citation obligations, trace-derived placement rules, and validation expectations. In Tolaria, a type is a category lens: it changes grouping, chips, instances, default views, sort, and templates. That choice is coherent for personal knowledge because capture and browsing stay cheap. It is insufficient for a methodology KB where future agents need to know not just that a document is a "review" but what work they may trust it to have done.

Tolaria's consumer-surface design is stronger than the current review's simple "desktop cockpit" framing. It differentiates human inspection, UI-guided agent help, raw-file agent work, and MCP registration. The important tradeoff is that the in-app AI panel constructs a product-defined context snapshot. That snapshot can improve activation because the agent gets the active note and visible vault shape before searching, but it can also hide relevant material if the snapshot boundary is too narrow. Commonplace mostly leaves this boundary to the agent's shell-search behavior, which is more transparent but less ergonomic.

Tolaria's evidence model is practical but shallow. Git history and files-first storage make it easy to inspect where a note came from, but the app does not attach confidence, review state, source quotations, extraction logs, or validation status to memories. Saved views and type documents can help a future agent decide what to read. They do not tell the agent whether a claim has been checked.

Tolaria should not be placed in trace-derived learning. Pulse and AutoGit preserve activity; the AI panel can run agents that edit files; the app can host OpenClaw or assistant memories as markdown. None of the inspected code turns transcripts, tool traces, git events, or repeated task trajectories into durable lessons, rules, procedures, tests, or model updates. Tolaria activates and preserves memory, but it does not itself distill traces into system-definition artifacts.

Borrowable Ideas

Managed guidance with custom-preservation states. Commonplace already owns AGENTS.md conventions, but Tolaria's missing/broken/managed/custom classification is a clearer lifecycle for installed KB guidance. In commonplace, commonplace-init could seed or repair guidance files while refusing to overwrite custom local instructions. Ready to borrow for installation and upgrade flows.

Saved views as editable work queues. Tolaria's views/*.yml files make recurring filters inspectable and agent-editable. Commonplace has generated indexes and selectors, but work queues such as "reviews needing freshness pass" or "seedlings by collection" are mostly command outputs. A small view-file format could make those surfaces stable without turning them into durable notes. Needs one concrete recurring workflow before implementation.

Context snapshot as a workshop artifact. The AI panel snapshot is useful because it names the active note, visible list, filter, references, and vault metadata in one structured block. A commonplace workshop could benefit from a generated current-context.md or JSON artifact that records the active target, loaded source set, validation state, and intended output. Promising for handoffs, but should remain workshop-local until a real handoff pain recurs.

Disposable cache with serious write discipline. Tolaria's cache replacement path is more robust than many "just write JSON" indexes: it versions entries, checks git HEAD, reparses changed files, uses a lock file, writes a temp file, fsyncs, renames, and guards against concurrent replacement. If commonplace adds an operational cache beneath generated indexes, this is the right posture. Ready only when a cache exists; YAGNI for current static indexes.

Relationship neighborhood reports. Neighborhood mode is a usable local navigation primitive: outgoing relationships first, inverse/backlink groups next, source pinned, duplicates allowed when multiple relations apply. A commonplace-neighborhood <path> report could group typed outbound links, backlinks, same-type siblings, tags, review warnings, and source snapshots. Ready as a read-only report idea.

Crash-safe relocate internals. Commonplace already routes renames through relocation tooling. Tolaria's staged rename transaction, backup, manifest, recovery, no-clobber persist, and failed-backlink count are a concrete implementation reference if relocation becomes more automated. Ready to borrow for hardening an existing command, not as a new feature.

Curiosity Pass

The architecture doc overstates the MCP write surface. The doc lists 14 MCP tools, including create, append, edit-frontmatter, delete, link, and list. The stdio server currently exposes six tools and the WebSocket bridge exposes read/search/context plus UI actions, not durable write handlers. This may be documentation drift, but it changes the memory-system interpretation: Tolaria is currently an orientation and activation MCP server, not a full vault mutation API.

Convention over configuration is doing two jobs. It makes vaults easier for agents because common fields mean less custom instruction. It also keeps the app from needing strict schemas. Those goals can conflict: the same looseness that helps adoption also limits trust. A future Tolaria validation layer would have to be optional or per-type, or it would undermine the product's capture-first philosophy.

The AI panel is a consumer surface with its own authority. The user sees the active note; the agent receives a structured snapshot; MCP tools can search/read beyond it. That makes the UI a context scheduler. If Tolaria later adds summarization or memory promotion, the snapshot builder will become one of the most important pieces of the memory architecture.

Path boundaries are stronger than semantic boundaries. Tolaria is careful about staying inside the active vault. It is less opinionated about whether a write should happen, whether a note is stale, or whether a relationship label carries valid semantics. This is the right split for a general desktop app but a weak governance story for a methodology KB.

No trace-derived learning placement. Tolaria preserves and activates files; it does not currently extract durable memory from agent traces, transcripts, trajectories, rollouts, or event streams.

What to Watch

  • Whether the MCP implementation grows the write tools described in the architecture doc, or whether the docs narrow to the read/search/UI tool surface.
  • Whether saved views become a general work-queue substrate for agents, with stable conventions agents can edit directly.
  • Whether AGENTS.md restoration becomes configurable by vault or type, which would make Tolaria a stronger reference for packaged agent guidance.
  • Whether the AI panel begins persisting chats, summarizing sessions, or promoting actions into notes; that would change the trace-derived learning placement.
  • Whether Tolaria adds optional validation for type documents without abandoning "types as lenses."
  • Whether the Linux expansion and release tooling change the adoption story from Mac personal vault cockpit to cross-platform agent-memory workspace.
  • Whether relationship configuration files such as config/relations.md and config/semantic-properties.md become active enough to form a middle layer between freeform relationships and commonplace-style link contracts.

Relevant Notes: