Tolaria: un «segundo cerebro» local en Markdown para la era de los agentes de IA

Una aplicación de escritorio (macOS, Windows y Linux) para gestionar bases de conocimiento en Markdown: archivos planos con frontmatter YAML, Git como capa de historial y sincronización, editor bloque a bloque tipo Notion y agentes de IA (Claude Code, Codex y otros) integrados de primera clase.

Qué es

refactoringhq/tolaria es una aplicación de escritorio abierta (licencia AGPL-3.0) para gestionar bases de conocimiento en Markdown. Cada nota es un archivo .md plano con frontmatter YAML; cada «vault» (bóveda) es una carpeta que puede ser un repositorio Git; la interfaz ofrece un editor rico bloque a bloque (comandos slash, wikilinks con autocompletado, tablas, hojas de cálculo, vistas guardadas) sobre esos archivos, sin base de datos ni formato propietario.

Tres usos que el README declara explícitamente:

Operar un «segundo cerebro» y conocimiento personal.
Organizar la documentación de una empresa como contexto para IA.
Almacenar la memoria y los procedimientos de asistentes/agentes (el README menciona OpenClaw y asistentes en general).

El autor, Luca Rossi (cuenta LucaRonin en GitHub, lucaronin en X), lo construyó para gestionar su propio workspace de más de 10.000 notas, acumulado durante cinco años escribiendo el newsletter técnico Refactoring (refactoring.fm, más de 170.000 suscriptores según su sitio web, y 300+ artículos). La documentación pública vive dentro del propio repositorio (carpeta site/, publicada en GitHub Pages) y el sitio oficial es tolaria.md.

Origen

El repositorio se creó el 14 de febrero de 2026 bajo la organización GitHub refactoringhq. docs/VISION.md (escrita por «Brian» a partir de conversaciones con Luca Rossi entre febrero y marzo de 2026) documenta la génesis: tras cinco años de tiempo completo escribiendo en Refactoring, Rossi acumuló 9.000+ notas en un workspace de Notion, «aprendió mucho sobre gestión del conocimiento, productividad y, más recientemente, sobre trabajar bien con IA sobre documentos», y al no encontrar ninguna herramienta existente que le encajara, construyó una.

Origen de Tolaria: un archivo local de 10.000 notas acumulado en cinco años de un newsletter técnico

Un detalle del mismo documento: Tolaria empezó en Swift, pero Luca se topó con limitaciones reales en la parte del editor Markdown (es difícil construir algo «tipo Notion» en Swift) y migró a Tauri 2 + React + TypeScript (con src-tauri en Rust). El propio Luca lo confirma en Hacker News ante la crítica de que es un «webwrapper».

La narrativa de lanzamiento también queda documentada: el 22 de abril de 2026 publicó el sitio tolaria.md en HN (hilo 47865031, 3 puntos, 0 comentarios) y al día siguiente, el 23 de abril de 2026, el «Show HN» principal (47882697, 318 puntos, 142 comentarios). En el texto del envío Luca se presenta y explica: construyó Tolaria para sí mismo (10K notas, 300+ artículos en más de 6 años de newsletter), es offline-first, file-based, tiene Git de primera clase y «opiniones fuertes» sobre cómo organizar notas (types, relationships).

El VISION.md explica además por qué es gratis y open source: el éxito del proyecto funciona como canal de reputación y captación para el newsletter Refactoring («no es un producto buscando mercado; es una herramienta construida por su primer usuario power, para una audiencia que ya lo conoce y le confía»). La primera nota de release estable conservada en el repositorio (release-notes/stable-v2026.5.2.md, mayo de 2026) ya incluía soporte de interfaz en polaco, lo que marca el punto de partida de los «stable».

Filosofía y principios

El README declara nueve principios verificables:

Files-first (archivos ante todo) — las notas son Markdown plano: portables, editables con cualquier editor, sin paso de exportación.

Filosofía files-first de Tolaria: notas Markdown planas con frontmatter YAML, sin base de datos ni formato propietario

Git-first — cada vault es un repositorio Git: historial completo, cualquier remoto, cero dependencia de servidores de Tolaria.
Offline-first, cero lock-in — sin cuentas, sin suscripciones, sin nube.
Open source — gratis y abierto; lo construyó para sí mismo y para compartirlo.
Standards-based — Markdown + YAML frontmatter; nada de formatos propietarios.
Types as lenses, not schemas (tipos como lentes, no como esquemas) — los tipos son ayudas de navegación, no mecanismos de imposición: sin campos obligatorios ni validación.
AI-first but not AI-only — un vault de archivos funciona muy bien con agentes de IA, pero se puede editar con cualquier herramienta; soporta rutas de configuración para Claude Code, Codex CLI y Gemini CLI y provee un archivo AGENTS.md para que los agentes lo interpreten.
Keyboard-first — diseñada para power users: editor y command palette centrados en el teclado.
Built from real use — nació para gestionar 10.000+ notas propias; «cada feature existe porque resolvió un problema real».

Editor bloque a bloque tipo Notion, diseñado keyboard-first: command palette, comandos slash y wikilinks

El documento de visión añade la capa metodológica — «se entrega el método junto con la herramienta» (tool and method, together):

Ontología del conocimiento: dos ejes (una vez / recurrente × multi-sesión / sesión única) que generan Project, Responsibility, Procedure y Task, más contexto: Notes, Topics, Events, People.
El conocimiento tiene un propósito: «las notas existen para hacer cosas», no para almacenarse.
Dos fases: captura y organización. Capturar rápido y sin fricción; organizar de forma deliberada y periódica (el Inbox muestra las notas sin salidas relacionales; el objetivo es «Inbox Zero» semanal; borrar más del 50% de lo capturado «es normal y saludable»).

Flujo de captura y organización: bandeja de entrada rápida, revisión periódica y objetivo semanal de Inbox Zero

Convention over configuration: campos con significado (status:, Workspace:, Belongs to:, start_date:/end_date:) disparan comportamiento rico sin configurar nada; los overrides viven en archivos del vault (config/relations.md, config/semantic-properties.md).
Por qué no Obsidian (sección dedicada en el VISION): Obsidian es una «lienzos en blanco» infinitamente configurable y trata a Git como un añadido (su modelo de negocio gira en torno al sync propietario); Tolaria es opinada, trae un framework completo de conocimiento por defecto y Git como ciudadano de primera clase.

Cómo funciona

Modelo de datos. Un vault es la carpeta que la app lee y escribe; el sistema de archivos es la única fuente de verdad y el estado de la app y la caché se derivan de los archivos. Las notas son Markdown con YAML frontmatter; los adjuntos son archivos normales dentro del vault; las definiciones de tipo y las vistas guardadas también son archivos.

Types. El campo type: asigna una nota a un tipo (Project, Person, Topic, Procedure, Event, o cualquier categoría propia). Tolaria no infiere el tipo por la ubicación en la carpeta. Se prefieren los tipos a las carpetas. Los «type documents» (notas con type: Type en frontmatter) definen icono (_icon), color (_color), etiqueta y orden en la barra lateral, propiedades pinnadas y plantillas de nota nueva.

Relationships. Cualquier campo de frontmatter que contenga wikilinks se convierte en relación. Los campos por defecto son belongs_to, has y related_to; los campos personalizados con wikilinks se detectan dinámicamente. Las relaciones por defecto tienen inversas calculadas automáticamente (si una nota belongs_to un proyecto, el proyecto la muestra bajo has). Los enlaces entrantes y las relaciones inversas aparecen en el panel de propiedades y en el modo Neighborhood (vista de grafo alrededor de la nota seleccionada).

Tipos como lentes: Project, Responsibility, Procedure, Task, Note, Topic, Event y Person con relaciones inversas automáticas

Inbox. Sección derivada (no una carpeta) que muestra todas las notas sin relaciones salientes. Es opcional: se desactiva en Settings > Workflow.

Git integrado. Tolaria actúa como cliente Git ligero del vault: historial y diff de todo el vault y por nota, commit local, pull/push, detección y resolución de conflictos y conexión de remotos. Usa la autenticación del Git del sistema (GitHub CLI, SSH, credential helpers, Keychain). AutoGit crea commits y pushes automáticos conservadores tras pausas de edición o cuando la app queda inactiva. Un vault puede ser una carpeta dentro de un repo mayor: Tolaria descubre el worktree padre pero limita el alcance de status/diffs/commits a los archivos del vault.

Git integrado en Tolaria: historial y diff por vault, commit local, pull/push y AutoGit tras pausas de edición

IA, dos vías. (1) Agentes de código: el panel de IA transmite agentes CLI locales a través de una capa de eventos normalizada. Agentes soportados documentados: Claude Code, Codex, GitHub Copilot, OpenCode, Pi, Antigravity CLI, Kiro y Hermes Agent. Cada agente conserva su propia autenticación. Dos modos de permiso por vault: Vault Safe (limitado a herramientas de archivo, búsqueda y edición) y Power User (permite shell local acotado al vault activo, para agentes que lo soportan). Algunos agentes exponen un selector de modelo (Codex y los alias documentados de Claude Code). (2) Modelos directos: chat sobre el contexto de la nota (nota activa, contexto enlazado e historial de conversación), sin herramientas de escritura del vault ni shell. Provedores: Ollama, LM Studio (locales) y OpenAI, Anthropic, Gemini, OpenRouter o endpoints OpenAI-compatible. El prompt inline se escribe con Cmd+K + espacio.

MCP. Tolaria incluye un servidor MCP (directorio mcp-server/, Node.js con ws-bridge.js y vault-lifecycle.js) para herramientas externas. El flujo de configuración puede escribir la entrada MCP de Tolaria en las config de Claude Code, Antigravity CLI y Cursor, o en una ruta de config MCP genérica, o copiar el snippet JSON exacto para setup manual; es explícito (cerrar el diálogo no toca archivos de terceros). Herramientas: buscar y leer contenido del vault, crear notas, actualizar una nota completa (con un guard de modification-time opcional para read-modify-write más seguro) y appending a notas existentes; las escrituras refrescan Tolaria tras el cambio.

Agentes de IA locales conectados al vault: modos Vault Safe y Power User, más servidor MCP con puentes WebSocket

Multi-vault. Se pueden cargar varios vaults registrados en un grafo unificado (Settings -> Vaults -> «Use multiple vaults at the same time»); los wikilinks cross-vault usan alias estables del vault destino, p. ej. [[team/projects/alpha]].

Ecosistema multi-vault: bóvedas separadas conectadas por wikilinks cross-vault con alias estables

El ecosistema

Repositorios hermanos de la organización refactoringhq (API de GitHub, 25 de agosto de 2026):

refactoringhq/portent (69 estrellas) — especificación abierta para bases de conocimiento portables. Define 8 tipos por defecto en dos grupos: PORT (Project, Operation, Responsibility, Task — cosas accionables) y ENTP (Event, Note, Topic, Person — registros de conocimiento); dos relaciones por defecto (belongs_to, related_to) y un ciclo de vida de tres estados (capture → organize → archive). «Portent es más fácil de implementar en Tolaria, pero está diseñado para ser portable a través de sistemas file-based, apps de notas, tools de docs y vaults legibles por agentes». Sitio: portent.md.
refactoringhq/portent-vault-template (84 estrellas) — plantilla de vault de arranque con las definiciones de tipo por defecto de Portent.
refactoringhq/tolaria-getting-started (31 estrellas) — el vault de «Getting Started» que la app ofrece clonar en el primer arranque (se clona localmente y se desconecta de su remoto para que el tutorial sea seguro de editar).

Forks y ports de la comunidad:

primitiver/tolaria-zh (6 estrellas) — traducción al chino del README y del material del proyecto (versión canjeada del README en mandarín).
hhungxun/tolaria-docs — sitio de documentación standalone para Tolaria construido con Astro y Starlight (publicado en GitHub Pages).
feir/Save-To-Tolaria — extensión de Chrome que guarda contenido web como notas Markdown limpias en un vault de Tolaria: extracción por capas (APIs de Twitter/X vía FxTwitter, Reddit, GitHub, YouTube; luego Defuddle; luego Jina Reader como fallback), frontmatter aware de los tipos del vault, reglas por patrón de URL, resumen opcional vía LLM (endpoints OpenAI- o Claude-compatibles), atajo Cmd+Shift+S/Ctrl+Shift+S y refresh en vivo del vault por WebSocket.
pcamp96/tolaria-sync — cliente de sincronización en vivo para el editor de Tolaria (proyecto incipiente).

Proyectos relacionados y competidores con anclaje real (descritos en el hilo de HN del lanzamiento y en GitHub):

sig-ai-app/sig-releases (82 estrellas, creado el 24 de abril de 2026, un día después del Show HN) — «Sig — Your AI finally knows what’s going on at work». El autor, Adam Ramirez (smadam9 en HN), lo anuncia en el propio hilo: «te adelanté un día. macOS, Markdown plano, versionado con Git, diseñado como contexto para agentes de IA. La diferencia es dónde arranca en el workflow: Tolaria parece destacar organizando conocimiento que ya existe; Sig…» (el repo redirige desde adamjramirez/sig-releases).
rillmd/rill (6 estrellas) — PKM con journaling por voz y distilación de conocimiento con IA, «Markdown + Git», construido como capa de vault sobre Claude Code; mencionado por tarr1124 en el hilo de HN.
Alternativas citadas por usuarios en HN (solo las verificables en el hilo): octarine.app (mencionado por stock_toaster), HelixNotes (codeberg.org/ArkHost/HelixNotes, mencionado por Barbing), mdnb.app (app nativa de Markdown para macOS, mencionada dos veces por nicoritschel).

Herramientas que Tolaria consume/sponsora: Codacy, CodeScene, CircleCI y Unblocked figuran como panel de sponsors en el README.

Estado oficial / semioficial

Tolaria no ha sido aceptada en ningún marketplace oficial ni cuenta con endorsement de un vendor; su estatus es el de un proyecto open source de un autor/organización independiente. Lo que sí se pudo verificar en esta ejecución:

Homebrew: existe un cask oficial en el registro de Homebrew (brew install --cask tolaria), confirmado mediante la API de formulae.brew.sh (nombre «Tolaria», descripción «Markdown knowledgebase manager»). Es la vía de instalación soportada en macOS y un indicador de adopción comunitaria estándar.
Especificación propia: la org publicó Portent como «open specification for portable knowledge base systems» (portent.md), una apuesta por convertirse en el punto de referencia de facto para vaults legibles por agentes, aunque todavía sin adopción externa verificable más allá de la propia familia de repos de refactoringhq.
Compatibilidad de facto con el ecosistema de agentes: al exponer un servidor MCP y archivos AGENTS.md/CLAUDE.md/GEMINI.md, Tolaria se encaja en el patrón dominante «vault local + agente CLI» usado con Claude Code, Codex, Cursor y similares, sin certificación formal de ninguno de esos vendors.
Trending: el repositorio alcanzó las listas de trending de GitHub (varios Shorts de YouTube lo titulan «GitHub Trending Repositories: refactoringhq/tolaria» y «tolaria - GitHub Trending Today»), aunque no se verificó una captura de la propia lista.
Marca: existe trademarks.md en el repo; el README aclara que el nombre y el logo de Tolaria siguen cubiertos por la política de marcas del proyecto (la licencia es AGPL-3.0-or-later, pero la marca queda aparte).

Guía rápida de uso

Instalación y primer arranque

macOS (Homebrew):
```
brew install --cask tolaria
```
Descarga manual (macOS, Windows o Linux) desde la página de descargas: https://tolaria.md/download/ (o desde los releases de GitHub). Estado por plataforma según la documentación: macOS es la principal (Apple Silicon e Intel, con Homebrew); Windows («Supported, early»): instaladores NSIS y bundles de actualización firmados con Tauri; la documentación de instalación indica que la firma Authenticode del publisher se añadirá tras la provisión del certificado de Windows, y los dispositivos corporativos gestionados (SmartScreen/WDAC) pueden requerir aprobación de IT. Linux («Supported, early»): se publican AppImage, .deb y RPM; el comportamiento depende de WebKitGTK e integración de input-method de la distribución.
Primer arranque: Tolaria ofrece tres opciones: crear o clonar el Getting Started vault (clonado localmente y luego desconectado de su remoto), abrir un vault local existente (cualquier carpeta de archivos Markdown), o crear uno nuevo vacío. Comandos iniciales documentados: Cmd+K/Ctrl+K abre el command palette; New Note; Open Getting Started Vault; Reload Vault.
Compilar desde el código (para contribuir o desarrollar): prerequisitos Node.js 20+, pnpm 8+, Rust stable, y macOS o Linux. En Linux (Tauri 2) se requieren WebKit2GTK 4.1 y GTK 3 (p. ej. en Debian/Ubuntu: sudo apt install libwebkit2gtk-4.1-dev build-essential ... librsvg2-dev libsoup-3.0-dev patchelf). Luego:
```
pnpm install
pnpm dev        # modo mock en el navegador (http://localhost:5173)
pnpm tauri dev  # app de escritorio nativa
```
En Linux, el servidor MCP incluido arranca el binario node del sistema en runtime, así que conviene instalar Node desde el gestor de paquetes si se quiere el flujo de herramientas de IA externas.

Flujos de trabajo habituales

Capturar y luego organizar: crea una nota (o gárdala desde la web); queda sin relaciones salientes y aparece en el Inbox. En la pasada semanal de organización: ponle un H1 claro, asigna type:, añade status/fechas/URL si corresponde, y conecta con wikilinks o campos de frontmatter (belongs_to, related_to). Al conectarla, sale del Inbox automáticamente.
Versionar y sincronizar con Git: abre el chip de remoto en la barra de estado inferior (o Add Remote desde la command palette), pega la URL del remoto y confirma el nombre; Tolaria usa la autenticación del Git del sistema (SSH, GitHub CLI, Keychain). Para checkpoint automático, activa AutoGit en Settings: commitea y hace push tras una pausa de inactividad.
Trabajar con IA: en Settings, elige el AI target por defecto — un agente de código (Claude Code, Codex, GitHub Copilot, OpenCode, Pi, Antigravity CLI, Kiro o Hermes Agent) para edición de vault con herramientas, o un modelo local/API para chat sin escritura. Para un prompt puntual mientras escribes: Cmd+K + espacio y escribe el prompt en el contexto de la nota. Revisa los cambios como edición de archivos: diff e historial Git antes de commitear.
Conectar un agente externo por MCP: abre el flujo de setup MCP desde la app; elige escribir la entrada en la config de Claude Code, Antigravity CLI o Cursor, en una ruta MCP genérica, o copia el snippet JSON exacto para configuración manual. El agente podrá entonces buscar/leer el vault, crear notas, actualizarlas (con guard de mtime opcional) o appending contenido.

Configuración esencial

La carpeta del vault — el único «archivo» imprescindible: tus notas son los .md dentro; todo lo durable (tipos, vistas guardadas, adjuntos) viaja con ella.
type: en el frontmatter de cada nota — asigna la nota a su tipo; es la principal palanca de organización (la barra lateral, plantillas y propiedades pinnadas dependen de ello).
Documentos de tipo (type: Type) — definen icono, color, orden, propiedades pinnadas y plantillas de nota nueva; empezar copiando el vault portent-vault-template da una base completa.
config/relations.md y config/semantic-properties.md (según VISION.md) — los overrides de las convenciones por defecto: qué campos de relación aparecen y cómo se renderizan las propiedades.
Settings > Workflow / Settings > Vaults — activar/desactivar el Inbox y habilitar el multi-vault unificado, respectivamente.

Trampas frecuentes y soluciones

Windows y Linux son «Supported, early». Issues abiertos documentados al momento de esta investigación: #1145 (wikilinks [[]] que no funcionan en la app de Windows), #1155 (en Windows, en notas tipo hoja de cálculo el título pasa a ser la ruta completa del archivo y se pierden ediciones de celdas), #1077 (arrastrar/soltar archivos y reorganizar carpetas no funciona).
El cask de Homebrew ha mostrado la última versión incorrecta: issue #1160 («Incorrect latest Tolaria version via Homebrew»). Verifica en la página de releases si la versión del cask parece vieja.
Carpeta #recycle en NAS Synology: issue #1159 — el vault crashea con un error de opdir al escanear la carpeta de reciclaje del NAS; la solución práctica es excluir ese vault de NAS o borrar/renombrar la carpeta.
Importación desde Obsidian: el flujo «copiar la carpeta con cp -a y abrirla como vault» es el camino documentado de facto (vía discussions y el hilo de HN), pero wkcheng reportó en el Show HN (con reproducible 100%): tras el primer commit Git, el ordenamiento por «última modificación» dejaba de funcionar; el autor respondió que lo investigaría. Si importas un vault grande, revisa el ordenamiento temprano.
La app reescribe archivos / búsqueda MCP extraña: issue #1144 documenta Tolaria reescribiendo archivos y un problema de búsqueda por MCP; si un agente externo no ve tus cambios, comprueba si la app los refrescó tras la escritura (las escrituras MCP refrescan Tolaria, pero no al revés siempre).
La app móvil es experimental: #1102 documenta que la app móvil (apps/mobile, React Native) hace trap (crash) en iPads físicos —no solo en simulador— por una API de comandos de teclado solo disponible en simulación. No la dependas para captura móvil.
La crítica de «webwrapper»: varios usuarios de HN objetan que Tauri es un contenedor de navegador (ikdiendoehdj: «absolutely disgusting, either go native or don’t bother»). La respuesta del autor: empezó en Swift y se topó con límites del editor Markdown; la réplica técnica más matizada la dio msephton (que construyó un editor Markdown para iOS con restyle de 8ms). Si esto te bloquea, prueba la app antes de decidir.
Linux: sin WebKit2GTK 4.1 + GTK 3 el build falla; y sin node instalado el servidor MCP no arranca en el flujo de herramientas externas.

Integraciones y migración

Agentes de código: el panel de IA integra directamente Claude Code, Codex, GitHub Copilot, OpenCode, Pi, Antigravity CLI, Kiro y Hermes Agent (se detectan los instalados en el equipo y usan sus propias credenciales); los modos Vault Safe / Power User acotan el alcance.
MCP: servidor incluido con setup asistido para Claude Code, Cursor y Antigravity CLI, o JSON genérico.
Navegador: la extensión comunitaria feir/Save-To-Tolaria (Cmd/Ctrl+Shift+S) guarda páginas como notas con frontmatter por tipo.
Migrar desde Obsidian/Logseq/Notion: abre directamente la carpeta de Markdown como vault (los vaults legacy de Obsidian funcionan; hay una discussion dedicada, #391, sobre vaults legacy). Desde Notion hay que exportar a Markdown antes.
Salir de Tolaria: no hay nada que migrar — tus archivos son Markdown plano + Git; cualquier editor, grep, o sistema de versionado los consume (principio «zero lock-in», explícito en el README y en el VISION).

Números del repo

Medición: 25 de agosto de 2026, API de GitHub.

Métrica	Valor
Estrellas	19.584
Bifurcaciones	1.360
Suscriptores (notificaciones)	51
Incidencias abiertas según la API	55
Commits (rama main)	3.672
Lenguaje principal	TypeScript
Licencia	AGPL-3.0-or-later
Creación	14 de febrero de 2026
Último push	24 de agosto de 2026
Último release estable	v2026-08-19 (19 de agosto de 2026)
Release alfa más reciente	alpha-v2026.8.24-alpha.0001 (24 de agosto de 2026)

Contribuidores principales que devolvió la API (de 24 en total): LucaRonin (3.409 contribuciones — prácticamente todo el desarrollo), github-actions[bot] (208), evolankakis (10), riipandi (5), the-jwoo (3), mvanhorn (3), AlessandroMason (3), oksusucha (3).

Caveats: open_issues_count (55) de la API de GitHub puede incluir PR abiertas, no es un conteo exclusivo de issues. watchers_count replica las estrellas; el número real de suscriptores a notificaciones es 51 (subscribers_count). El conteo de commits (3.672) se derivó del encabezado Link de paginación de la API de commits (rel="last"). La lista de releases muestra tags alfa diarios; /releases/latest apunta al estable v2026-08-19. El contador de estrellas visible en tolaria.md al momento de la consulta era 9.946 (valor en caché del sitio, desfasado respecto a la API).

Cómo contribuir

CONTRIBUTING.md documenta un proceso abierto y explícito:

Dónde se comparte qué: bugs → GitHub Issues (incluyendo versión de Tolaria, SO, pasos para reproducir, lo esperado vs. lo ocurrido, y capturas si ayuda); ideas y feature requests → Canny (https://tolaria.canny.io/), donde conviene upvotar lo que ya existe antes de construirlo.
PRs bienvenidas, con reglas: PRs pequeñas, enfocadas y fáciles de revisar; explicación breve del problema y la solución; no mezclar refactors no relacionados; para features grandes, primero comprobar Canny (evitar lo marcado «in progress»; lo marcado «planned» es buen objetivo de contribución).
Seguir el proceso de desarrollo de AGENTS.md, que documenta la disciplina de calidad del repo (usada también por los agentes de IA que trabajan en la base de código):
- TDD obligatorio: rojo → verde → refactor → commit, un ciclo por commit; para bugs, primero un test de regresión que falla.
- Suite de checks en cada push: pnpm lint && npx tsc --noEmit && pnpm test && pnpm test:coverage (frontend ≥70% de cobertura) y cargo test && cargo llvm-cov ... --fail-under-lines 85 (Rust ≥85%).
- CodeScene como gate de salud de código con umbrales tipo «ratchet» (solo suben, en .codescene-thresholds); Codacy como gate de seguridad con regla de cero hallazgos nuevos.
- Playwright para flujos core (abrir vault, crear/guardar/borrar nota, búsqueda, navegación de wikilinks, commit/push, resolución de conflictos); el smoke suite debe quedarse por debajo de 5 minutos.
- Localización: toda la copy de UI vive en src/lib/locales/en.json y se traduce a los idiomas objetivo de lara.yaml con pnpm l10n:translate (ya incluye polaco).
- PostHog: las features nuevas deberían emitir eventos de analítica (con metadatos seguros, sin PII ni contenido de notas).
- ADRs en docs/adr/ para decisiones de arquitectura; documentación (docs/ARCHITECTURE.md, docs/ABSTRACTIONS.md, docs/GETTING-STARTED.md) actualizada en el mismo commit que el cambio.
- CI/CD autoritativo: CircleCI (.circleci/config.yml) posee la validación, los builds de release cruzados, la publicación de GitHub Releases y de GitHub Pages.

Nota: AGENTS.md describe además el flujo interno del propietario (direct-to-main con commits cada 20–30 minutos, gestión de tareas en Todoist, excepciones documentadas aprobadas por el owner) — es el manual de sus agentes de desarrollo, no el flujo de ramas que debe seguir un contribuidor externo, que abre PRs según CONTRIBUTING.md.

Cómo lo recibió la comunidad

El hilo principal de Hacker News es 47882697 — «Show HN: Tolaria – Open-source macOS app to manage Markdown knowledge bases», enviado por lucaronin el 23 de abril de 2026, con 318 puntos y 142 comentarios. Hay un segundo envío menor, el sitio tolaria.md, en 47865031 (3 puntos, 0 comentarios, 22 de abril de 2026).

El entusiasmo, con nombres y argumentos concretos:

johntopia (usuario intensivo de Obsidian): «buen trabajo Luca, he sido heavy user de obsidian pero me gusta mucho tu concepto de inbox».
r0bbie: usaba Logseq pero nunca le gustó la UI; «limpio y me encanta el enfoque git-backed». Pidió dark mode.
Pym: «mejor que lo que yo planeaba construir para mí mismo. Me encanta la UI, me encanta que esté hecha con Tauri».
ajbd: «el principio de “types as lenses, not schemas” y el foco en estructura + relaciones realmente destacan».
tarr1124 contextualiza la discusión: Obsidian asume «humano lee y curatea; plugins opcionalmente mejoran», mientras que la cohorte AI-first (Tolaria, Sig y varios más) «asume que la IA lee y escribe como agente de primera clase».
fiatpandas pidió poder «ver» a la IA trabajando en el vault «como una sesión de Google Docs»; lucaronin respondió que el git-first es exactamente para eso: «puedes configurar a la IA como contributor de git y ver sus cambios claramente».
smadam9 (autor de Sig): «me ganaste la delantera por un día… la solapación de arquitectura es obvia: macOS, Markdown plano, versionado con Git, diseñado como contexto para agentes de IA».
crashabr mencionó a moment.dev, una startup temprana que hace presencia en vivo de agentes en vaults.

La crítica, también concreta:

jryio (la objeción más votada en espíritu): «solo otro trozo desechable de software mantenido por una persona que hace el 80% de lo que hacen otras apps, pero peor. Vida máxima 2 años». Recibió réplicas firmes: rglover («Por favor quítate esto. No quieres vivir en un mundo donde se desanime a individuos a construir cosas buenas»), lbreakjai, BirAdam («¿Sabías que eso describía una vez a GCC y Linux?»).
kskzjsjdjw: «¿Una maldita web app? Boo. No gracias». droidjj replicó: «al menos es Tauri».
ikdiendoehdj (crítica técnica repetida en varios hilos del comentario): «un webwrapper es absolutamente repugnante, o ve nativo o no molestes»; objetó también el riesgo del ecosistema npm. sdevonoes matizó: «no se trata de velocidad, sino del ecosistema npm: intento evitar correr dependencias npm en mi PC personal». lucaronin respondió que empezó en Swift pero se topó con límites reales del editor Markdown y que «Tauri es muy rápido».
antonkochubey: «¿Obsidian ya no hace prácticamente lo mismo?». dragonfax: «de alguna forma no sabía que Obsidian no era open source». lucaronin contestó con la lista de diferencias (tipos y relaciones, UX tipo Notion, Git first-class, decisiones de diseño para IA, y sobre todo: open source).
wkcheng reportó el bug de ordenamiento tras importar un vault de Obsidian y hacer el primer commit (reproducible 100%: cp -a del vault → abrir en Tolaria → «Restore Tolaria AI Guidance» → el sort por última modificación se rompe).
msephton: «me lo tomaría todo si fuera una app nativa de macOS».
enola-mag preguntó por Windows (en abril la app era «macOS app» según el título del Show HN; Windows/Linux ya están publicados como «supported, early»).

Discussions de GitHub (canal oficial de la comunidad): «iOS workflow» (#259, 12 comentarios), «Does Tolaria have support for Tabs» (#300, 12 comentarios), «Claude Code finished without returning a reply» (#389, 17 comentarios), «Legacy Obsidian vaults: reveal note in folder» (#391, 2 comentarios).

Video (búsqueda de YouTube el 25 de agosto de 2026): «Tolaria — The Markdown Knowledge Base Born For Claude Code» de Prism Labs (7:14, ~5.600 vistas); «Tolaria: A Markdown Second Brain Built for the Claude Code Era» de AwesomeFOSS (~7.300 vistas, compara Tolaria vs Obsidian vs Notion); «Tolaria GitHub Setup Guide: Markdown Knowledge Bases for Version-Controlled Personal Knowledge» de Alex Hitt (8:11, ~531 vistas, cubre MCP, AutoGit, Tauri/React/Rust y agent instruction files). Varios Shorts del nicho lo promocionan (2.400, 1.600 y 728 vistas; «Stop letting Notion hold your notes hostage», «I Finally Deleted Notion And Found The Ultimate Free Alternative»). El propio Luca publica tres walkthroughs de Loom en el README: cómo organiza su workspace, su workflow de inbox y cómo guarda recursos web.

Reddit y Product Hunt: no se pudieron verificar hilos o páginas de lanzamiento en esta ejecución (el endpoint JSON de Reddit devolvió una página anti-bot y PullPush no indexó posts relevantes; Product Hunt bloqueó la consulta tras verificación de Cloudflare). No se infieren reacciones que las fuentes no muestran.

Tolaria frente a otras propuestas

Proyecto	Coincidencia verificable	Diferencia verificable
Obsidian	Vault local de Markdown con wikilinks; ambos conviven sobre los mismos archivos.	Obsidian no es open source (lo señalan `dragonfax` y `lucaronin` en HN), su modelo gira en torno al sync propietario y Git es un añadido; Tolaria trae método propio (tipos, relaciones, inbox) y Git first-class, sin plugin ecosystem.
Notion	Editor rico bloque a bloque, «UX tipo Notion» (autodescripción del VISION).	Notion es SaaS con formato propietario en servidores remotos; Tolaria es archivos locales + Git, offline-first y sin cuenta.
Logseq	PKM local, Markdown, orientado a power users.	Logseq es un outliner con su propio modelo de archivos; en HN `r0bbie` lo deja por Tolaria por la UI y el enfoque git-backed.
Zettlr	Editor Markdown de escritorio con enfoque de escritura.	Zettlr es un editor (no un vault con tipos/relaciones ni IA integrada); en HN `morelikeborelax` relata que se cae cuando el Markdown cambia en segundo plano.
Typora	Editor Markdown WYSIWYG (sugerido por `astrocat` en HN para quien quiere «Bear Notes polish» sobre Markdown plano).	Editor simple, sin grafo de notas, sin Git, sin agentes de IA.
Sig (`sig-ai-app/sig-releases`, 82 estrellas)	macOS, Markdown plano, versionado con Git, contexto para agentes de IA (mismo autor de arquitectura según su propio comentario en HN).	Arranca desde el workflow de trabajo en equipo (commits a un repo central compartido) en vez de organizar conocimiento existente.
rill (`rillmd/rill`, 6 estrellas)	Vault de Markdown + Git con capa sobre Claude Code.	Añade journaling por voz y distilación de conocimiento; no tiene el framework de tipos/relaciones.

La comparación que más se repitió en el lanzamiento fue con Obsidian (la pregunta antonkochubey); la respuesta oficial del autor y del VISION es filosófica: Obsidian es lienzo en blanco infinitamente configurable; Tolaria es opinionada, con Git como capa de colaboración y IA como colaborador de primera clase.

Casos de uso

Escritores y creadores de contenido técnico (el caso del propio autor: 300+ artículos sostenidos sobre un vault de 10.000+ notas). El flujo documentado de «captura → evergreen notes → artículos» y el concepto de Inbox Zero dan un método completo, no solo un editor; el VISION documenta explícitamente que el output de los escritores son artículos y que las notas evergreen son la capa intermedia reutilizable.
Desarrolladores que operan agentes de código a diario (Claude Code, Codex, Copilot, OpenCode, Kiro, Antigravity, Hermes Agent). Tolaria les da un contexto persistente y navegable para sus agentes: servidor MCP con escrituras guardadas por mtime, modos Vault Safe/Power User, archivo AGENTS.md en el vault para instrucciones del agente, y Git como capa de auditoría de los cambios de la IA (diffs, historial, rollback) — el patrón «agent commits as a git contributor» que el autor defiende en HN.
Equipos pequeños que quieren documentar su producto como contexto de IA. El VISION describe la etapa 3 (equipos): la misma ontología (proyectos, responsabilidades, procedimientos, personas) escalada, con filtrado por workspace y control de acceso vía Git; el README declara explícitamente «organizar docs de la empresa como contexto para AI».
Migrantes de Notion que quieren propiedad local de sus datos. Offline-first, sin cuenta, sin suscripción, archivos planos exportables por construcción; el VISION apunta directamente a personas «frustradas con el rendimiento, la complejidad o el lock-in de Notion» y cómodas con Git.
Usuarios de Obsidian que quieren estructura sin plugin hunting. Se abre el vault existente directamente (discusión #391 sobre vaults legacy), y se gana el framework de tipos/relaciones/inbox con convenciones por defecto, Git first-class y open source — sin el plugin ecosystem.
Constructores de agentes/asistentes que necesitan memoria persistente. El README declara «store OpenClaw/assistants memory and procedures»; la combinación vault Markdown + Git + MCP + Portent (especificación de tipos y ciclo de vida) es una base legible tanto por humanos como por agentes, con la especificación portent pensada explícitamente para ser portable a otros sistemas.
Power users de teclado. Command palette (Cmd/Ctrl+K), shortcuts documentados y diseño «keyboard-first» declarado como principio; la app se opera casi íntegramente sin ratón.

Recursos

Repositorio: https://github.com/refactoringhq/tolaria
Sitio oficial / documentación: https://tolaria.md (docs en site/ del repo, publicadas en GitHub Pages; empezar por site/start/install.md y site/start/first-launch.md)
Descargas: https://tolaria.md/download/ · releases: https://github.com/refactoringhq/tolaria/releases · notas de release: carpeta release-notes/ del repo
Homebrew: cask tolaria (brew install --cask tolaria)
Repositorios de la organización: refactoringhq/portent (especificación, https://portent.md) · refactoringhq/portent-vault-template · refactoringhq/tolaria-getting-started
Walkthroughs oficiales (Loom, del autor): How I Organize My Own Tolaria Workspace · My Inbox Workflow · How I Save Web Resources to Tolaria
Video (YouTube): «Tolaria — The Markdown Knowledge Base Born For Claude Code» (Prism Labs) · «Tolaria: A Markdown Second Brain Built for the Claude Code Era» (AwesomeFOSS) · «Tolaria GitHub Setup Guide» (Alex Hitt) — ver sección de recepción para cifras de vistas
Hilos de HN relevantes: 47882697 (Show HN, 318 puntos, 142 comentarios) · 47865031
Comunidad: GitHub Discussions · Canny (feature requests) (no se verificó un servidor de Discord en las fuentes consultadas)
Docs de desarrollo: docs/GETTING-STARTED.md, docs/ARCHITECTURE.md, docs/ABSTRACTIONS.md, docs/adr/, AGENTS.md
Traducción a chino: primitiver/tolaria-zh · Extensión Chrome: feir/Save-To-Tolaria

Este artículo combina el README, CONTRIBUTING.md, AGENTS.md, docs/VISION.md y la documentación de usuario de site/ del repositorio, los repos hermanos de la organización refactoringhq, la API de GitHub (métricas, releases, contribuidores, issues, discussions), la API de Homebrew formulae, el hilo de Hacker News 47882697 completo, el sitio tolaria.md y la búsqueda de YouTube, consultados el 25 de agosto de 2026. Las cifras de estrellas y forks de los repositorios compañeros cambian con el tiempo. No se pudieron verificar hilos de Reddit ni página de Product Hunt en esta ejecución (bloqueo anti-bot); se omiten en lugar de inferirlos.