Tolaria
Type: ../types/agent-memory-system-review.md · Status: current
Tolaria is RefactoringHQ's local-first desktop app for managing markdown knowledge bases as git-backed, agent-readable vaults. It is not a memory model or background learner. Its memory value comes from a file/git storage substrate, a human authoring UI, derived indexes and relationship views, managed agent guidance files, AI context snapshots, and launch paths for local CLI agents that can work inside the active vault.
Repository: https://github.com/refactoringhq/tolaria
Reviewed commit: 7adecaea60f792f3f10f6ee5ed90fe9139eba99e
Last checked: 2026-05-16
Core Ideas
The vault filesystem is the canonical storage substrate. Tolaria's architecture says markdown files on disk win over cache and React state, and the Rust scanner implements that: scan_vault recursively reads non-hidden files, parses markdown frontmatter/body metadata, classifies recognized non-markdown files as text or binary, recovers pending rename transactions, and sorts entries by modification time (docs/ARCHITECTURE.md, src-tauri/src/vault/mod.rs). Ordinary markdown notes, attachments, media files, and source text files are knowledge artifacts when humans or agents read them as evidence, context, or reference. They are not hidden service objects.
The cache is derived activation state, not authority. scan_vault_cached stores VaultEntry JSON under ~/.laputa/cache/<vault-hash>.json, keyed by cache version, vault path, and git HEAD; it incrementally reparses changed, uncommitted, or diffed files, migrates old in-vault .laputa-cache.json, prunes stale entries, and writes via temp file plus lock and fingerprint checks (src-tauri/src/vault/cache.rs). The cache has system-definition authority only in the weak sense that it selects what the UI initially sees until reload. Its lineage is explicit enough to discard: full reload invalidates the cache and rebuilds from disk.
Types are markdown documents used as lenses, not schemas. Type is resolved from type: frontmatter, never from folder location; type documents are notes with type: Type whose frontmatter can define icon, color, order, sidebar label, template, sort, view, visibility, pinned/list properties, and instance defaults (docs/ABSTRACTIONS.md, src-tauri/src/vault/frontmatter.rs). The demo vault shows this concretely with type files such as type/project.md (demo-vault-v2/type/project.md). These documents are knowledge artifacts when read as descriptions of a category, and system-definition artifacts when Tolaria uses them to configure sidebar grouping, defaults, display, sort, and instance placeholders.
Saved views are symbolic query artifacts. View definitions are YAML files under views/ with name, icon, color, order, sort, display columns, and nested filter groups; Rust scans, saves, deletes, and evaluates them against VaultEntry metadata (src-tauri/src/vault/views.rs). The demo views/active-projects.yml is a small example of a persisted filter over type: Project (demo-vault-v2/views/active-projects.yml). Views are system-definition artifacts with routing and ranking/display authority over what becomes visible in the note list. They are not source notes, and they should be reviewed as query configuration rather than remembered facts.
Relationships and Neighborhood mode turn frontmatter and wikilinks into navigable activation. The parser treats any non-reserved frontmatter field containing [[wikilinks]] as a relationship and extracts body wikilinks separately (src-tauri/src/vault/frontmatter.rs). The note-list helpers build direct relationship groups, inverse groups, type instances, and backlinks around a selected entity; Neighborhood selection history then lets the user pivot through that local graph (src/utils/noteListHelpers.ts, src/utils/neighborhoodHistory.ts, src/hooks/useNeighborhoodSelection.ts). The relationships remain knowledge-artifact links in the notes, but the rendered neighborhood has activation authority: it changes what related material becomes salient before a human or agent asks a broad search question.
Managed agent guidance files are high-authority prose. Tolaria can seed or restore root AGENTS.md, plus CLAUDE.md and GEMINI.md compatibility shims that point back to it; it classifies missing, managed, broken, and custom guidance states before replacement (src-tauri/src/vault/config_seed.rs). The bundled agent docs also instruct agents to read the active vault's AGENTS.md first and then use generated Tolaria docs for product behavior (src-tauri/resources/agent-docs/AGENTS.md). A vault's AGENTS.md, CLAUDE.md, and GEMINI.md are system-definition artifacts when loaded by Claude, Codex, Gemini, or another agent because they instruct local conventions. The same files are only knowledge artifacts when browsed by a human.
The AI panel creates transient context snapshots, then delegates to external agents. buildContextSnapshot packages the active note body, frontmatter, open tabs, current note list, vault type summary, and explicitly referenced notes into JSON, truncating large active-note bodies with an instruction to call get_note before content-sensitive work (src/utils/ai-context.ts, src/components/useAiPanelContextSnapshot.ts). buildAgentSystemPrompt adds vault-scope, bundled-docs, wikilink, MCP, and Safe/Power User instructions (src/utils/ai-agent.ts). These snapshots are UI context artifacts: they have temporary system-definition authority for one agent turn, but they are not retained as canonical knowledge.
CLI-agent launch is implemented for Claude Code, Codex, OpenCode, Pi, and Gemini, not OpenClaw as a product adapter. The shared AiAgentId enum and frontend definitions list claude_code, codex, opencode, pi, and gemini (src-tauri/src/ai_agents.rs, src/lib/aiAgents.ts). The adapters spawn those CLIs in the active vault, pass transient Tolaria MCP configuration, and map their JSON events into normalized UI messages (src-tauri/src/claude_invocation.rs, src-tauri/src/codex_cli.rs, src-tauri/src/opencode_config.rs, src-tauri/src/pi_config.rs, src-tauri/src/gemini_config.rs). AGENTS.md mentions OpenClaw QA scripts for repository development, but that is not a Tolaria user-facing agent adapter (AGENTS.md).
MCP is mainly read/orientation plus UI activation at this commit. The stdio server advertises search_notes, get_vault_context, list_vaults, get_note, open_note, highlight_editor, and refresh_vault, all annotated read-only/idempotent except for UI signaling (mcp-server/index.js). The WebSocket bridge exposes a similar local tool surface and broadcasts UI actions over loopback-checked ports 9710 and 9711 (mcp-server/ws-bridge.js). vault.js itself is read-only: it searches markdown files, reads notes with parsed frontmatter, and returns vault context including root AGENTS.md instructions (mcp-server/vault.js, mcp-server/agent-instructions.js). The architecture docs still list create/edit/delete MCP tools, and useMcpBridge has stale create/append helper names, but those are not implemented in the actual server reviewed here (docs/ARCHITECTURE.md, src/hooks/useMcpBridge.ts). Write authority comes through app/native file operations and the launched agent's own edit tools, not through Tolaria MCP write tools at this commit.
Git is an operational substrate and activity record, not learned memory. Tolaria shells out to the git CLI for commits, remotes, status, history, and Pulse; git_commit stages all vault changes with git add -A, ensures local author identity, and retries unsigned only for signing-helper failure (src-tauri/src/git/commit.rs). Pulse reads git log --name-status for markdown changes and optional GitHub commit URLs (src-tauri/src/git/pulse.rs). AutoGit builds generic messages such as Updated 3 notes, commits or pushes mounted repositories, and refreshes status (src/hooks/useCommitFlow.ts, src/utils/automaticCommitMessage.ts). Git history and Pulse entries are audit knowledge artifacts. They do not become policies, notes, rules, or ranking models.
Write and relocate safety are first-class system-definition code. Tauri command boundaries canonicalize active or registered vault roots, reject path escapes, and validate writable targets through the nearest existing ancestor (src-tauri/src/commands/vault/boundary.rs). Saves and creates go through those boundaries, retry transient permission errors, and keep invalid path failures recoverable (src-tauri/src/commands/vault/file_cmds.rs, src-tauri/src/vault/file.rs). Rename and move operations stage content under .tolaria-rename-txn, persist with no-clobber semantics, recover interrupted transactions, and rewrite wikilinks across the affected vaults (src-tauri/src/vault/rename_transaction.rs, src-tauri/src/vault/rename.rs). These symbolic checks have enforcement authority over where notes and agent-triggered edits may go.
Comparison with Our System
| Dimension | Tolaria | Commonplace |
|---|---|---|
| Primary purpose | Desktop app for authoring, inspecting, git-syncing, and agent-activating local markdown vaults | Methodology KB framework with typed artifacts, validation, reviews, indexes, and operational conventions |
| Canonical storage substrate | User vault filesystem plus optional git history; app settings and cache live outside the vault | Git-tracked kb/ collections, source snapshots, generated indexes, review reports, type specs, and scripts |
| Artifact contracts | Conventions: type:, Type documents, saved view YAML, root guidance files, relationship wikilinks |
Explicit type specs, schemas, collection rules, validation, review gates, and curated/generated indexes |
| Activation | UI filters, saved views, Neighborhood mode, AI panel snapshots, MCP search/read/context, CLI-agent launches | rg, descriptions, links, indexes, skills, review bundles, validation, and authored instructions |
| Behavioral authority | Split across vault prose, type/view config, guidance files, CLI prompts, permission modes, path boundaries, and agent MCP config | Split more explicitly by knowledge artifacts, system-definition artifacts, validation, and review status |
| Trace-derived learning | No durable trace-to-rule or trace-to-note learner found | Treated as a distinct methodology axis requiring lineage, authority, and promotion rules |
Tolaria is closest to commonplace in its file-first instinct: retained artifacts remain inspectable files, git is available as history and sync, and derived state is rebuildable. It differs in audience and authority. Tolaria optimizes for a human-facing desktop workspace that can launch agents into the same vault; commonplace optimizes for agent-operated knowledge artifacts with explicit type contracts, review status, and validation.
The strongest design difference is that Tolaria treats types and views as flexible lenses, while commonplace treats type specs and collection conventions as stronger contracts. Tolaria's "types as lenses, not schemas" makes adoption light and human-friendly, but it means agents can infer organization without receiving a deterministic quality bar. Commonplace pays more cost to make artifact authority explicit before future agents rely on it.
The AI integration is also more product-shaped than commonplace. Tolaria builds a concrete context snapshot from the currently visible UI, injects bundled product docs, launches a selected local CLI agent, and gives that agent MCP read/orientation tools plus native file-edit authority according to Safe or Power User mode. Commonplace currently depends more on repository navigation and skills. Tolaria shows a practical activation layer for "what the user is looking at right now."
Read-back: both — agents can pull vault notes through MCP search/read tools, while AI-panel snapshots inject active UI context into launched agents.
Borrowable Ideas
Root guidance as a managed vault artifact. Commonplace already has AGENTS.md, but Tolaria's state model for managed, missing, broken, and custom guidance files is useful. A future commonplace command could detect whether agent guidance is canonical, custom, or stale before offering repair.
Saved view YAML as explicit activation. Commonplace indexes and search commands could borrow Tolaria's small YAML query surface for task-specific note sets, provided the files are classified as generated/configured system-definition artifacts and validated.
Neighborhood mode for local graph reading. Commonplace has authored links and backlink-like navigation through search. A focused "neighborhood" report around one note could expose direct outbound links, inverse links, shared tags, and candidate related notes without promoting a full graph database.
Context snapshots should include UI provenance and truncation metadata. Tolaria's AI snapshot tells the agent what is active, which list is visible, which notes are referenced, and when the active note is truncated. A commonplace workshop or review UI could use the same pattern before handing a local task to a coding agent.
Permission modes should be artifact-aware. Tolaria's Safe/Power User split is imperfect but concrete: it changes CLI flags, shell availability, and prompt instructions. Commonplace workflows that launch sub-agents could benefit from similarly named authority modes tied to writable roots, tool sets, and expected artifact classes.
Keep cache, UI state, and source files visibly separate. Tolaria's strongest operational hygiene is that caches are external and disposable, while vault notes remain canonical. Commonplace should preserve the same line for future embeddings, rankings, or rendered views.
Curiosity Pass
The docs overstate the MCP write surface. The architecture table lists create, append, edit-frontmatter, delete, link, and list tools, but the implemented stdio MCP server exposes read/search/context/UI-refresh tools only. That distinction matters for behavioral authority: current MCP mainly activates knowledge artifacts; launched agents perform writes through their own tool permissions.
The same markdown file can change authority depending on consumption path. A note with a procedure is a knowledge artifact when read casually, but can become a system-definition artifact if AGENTS.md, a type template, or an agent prompt tells a CLI agent to follow it. Tolaria enables that shift but does not label it inside the vault.
AI chat history is runtime state, not durable learning. AiAgentMessage history is held in React state and trimmed into future prompt text during the current panel session (src/lib/aiAgentConversation.ts). File-operation detection can refresh the vault after tool writes, but it does not mine conversations or tool calls into retained rules or notes (src/lib/aiAgentFileOperations.ts). Product analytics explicitly disables session recording and uses memory persistence (src/lib/telemetry.ts). That supports a "not trace-derived" classification.
Git history is visible but not interpreted. Pulse makes activity inspectable, and cache invalidation uses git changes, but there is no code path that derives durable lessons, type changes, saved views, guidance edits, or retrieval weights from commit history.
Write safety is stronger in native app paths than in external agents. Tauri commands enforce the active-vault boundary, but Power User modes deliberately let shell-capable CLI agents run with broader agent-native edit/shell tools inside the vault. The prompt and CLI flags constrain those agents, yet the strongest enforcement still depends on the selected agent's own sandbox.
OpenClaw is not a Tolaria adapter here. The repository development instructions reference OpenClaw QA scripts, and the README mentions OpenClaw memory/procedures as a use case, but the app's implemented adapter list is Claude Code, Codex, OpenCode, Pi, and Gemini.
What to Watch
- Whether MCP write tools are implemented, removed from docs, or kept as an aspirational surface. That change would materially increase Tolaria MCP's behavioral authority.
- Whether Type documents evolve from lenses into schemas with validation, required fields, or migration rules.
- Whether saved views gain review, provenance, or generated-view lineage as they become more important to agent activation.
- Whether AI chat or tool traces are ever distilled into durable notes,
AGENTS.mdguidance, type templates, saved views, rankings, or policies. - Whether Safe/Power User modes stay aligned across Claude, Codex, OpenCode, Pi, Gemini, direct models, and external MCP clients.
- Whether AutoGit commit records become an input to summarization or governance rather than remaining generic activity/audit history.
Relevant Notes:
- Knowledge artifact - classifies: ordinary vault notes, attachments, git history, Pulse entries, and MCP-read note contents when consumed as evidence or context.
- System-definition artifact - classifies: type documents, saved views, root guidance files, CLI-agent prompts, permission modes, MCP configs, and path-boundary code when they instruct, route, configure, or enforce behavior.
- Behavioral authority - sharpens: the same markdown or YAML surface has different force depending on whether a human reads it, Tolaria renders it, or an agent is instructed by it.
- Storage substrate - defined-in: Tolaria separates canonical vault files, external app settings, external cache, runtime React state, MCP subprocesses, and git history.
- Knowledge storage does not imply contextual activation - exemplifies: Tolaria's memory effect comes from activation surfaces such as views, neighborhoods, snapshots, and MCP tools, not from storing markdown alone.