Sonatelle

A self-hosted notes app that can't lose a note

My own notes app, running on my own machine. Nested projects, history and full-text search on top; underneath, a cache that can't go stale, four independent backup layers, offline editing, and an MCP server so AI agents can read and write my notes.

Year
2026
Category
Full-Stack, Self-Hosted
Stack
TypeScriptReactNode.jsHonoSQLiteRedisMCPDockerTailscale
Sonatelle

Sonatelle is a quiet notes app: projects inside projects, stars, a guitar pick for the important ones, and every note kept in history. It's built to run on a machine at home and reach my phone and laptop privately. The interesting part is underneath, because I wanted three things a hosted app wouldn't give me: my notes on my own machine, readable by Claude, and impossible to lose.

How it fits together

Sonatelle reads and writesBrowserHTTP + live eventsAgentsMCP at /mcpServerNode + HonoReads, fastest firstMemoryL1RedisL2SQLiteprimaryReplicafallbackWritesSQLite primarywrite + event, togetherOpen browserslive over SSERedis Streamsonatelle:eventsReplica + mirrorcopy + git commit
Reads try the fastest copy first. Every write lands with its event in one transaction, and that event is what tells everyone else.

A cache that can't go stale

Reads go memory first, then Redis, then the SQLite primary, then a replica. The usual cache problem is invalidation: forget to clear a key and someone sees an old note. Here nothing is ever invalidated. Every cache key carries the change number of what it holds, like note:abc:s1042, so a write simply makes readers ask for a new key. Old entries just age out.

  • If Redis is slow or down, a circuit breaker skips it for a while and reads go straight to SQLite. The app gets slower, never broken.
  • When many requests miss the same key at once, they share a single load instead of all hitting the database.
  • Search runs on the server with SQLite's full-text index, so it stays fast as the library grows.

One write, everyone told

Every change is written in the same SQLite transaction as an event row, the outbox pattern. Once it commits, that event reaches any open browser over Server-Sent Events, nudges the replica and the git mirror, and lands on a Redis Stream. If Redis is away, events wait in the outbox and go out later, so nothing is half-announced.

I left Kafka out on purpose. A broker cluster for one person's notes is a JVM and a lot of moving parts for nothing Redis Streams doesn't already give: an append-only log with consumer groups. Because of the outbox, adding Kafka later would be one more sink, not a rewrite.

Notes that can't get lost

Sonatelle recovery chain and backupsStart-up: the first healthy copy winsPrimaryintegrity checkReplicarefreshed after writesSnapshotnewest healthy oneNew databaseonly if all else failsBackups, each on its ownSnapshotsevery 30 min, 48 keptGit mirrorevery note as MarkdownNote historyone-click restoreExportone JSON file
Start-up takes the first healthy copy it finds. The backups underneath don't depend on each other, so losing one leaves the rest.
  • Snapshots: a full, checked copy of the database every 30 minutes after changes, plus at start-up and shutdown. The newest 48 are kept, plus one a day for 30 days.
  • A Markdown mirror in git: every note as a .md file in folders matching its projects, committed a few seconds after changes and pushed to a private repo. Readable in any editor even if Sonatelle is gone.
  • Note history inside the app, with one-click restore, and a one-file JSON export from Settings.
  • If the primary database is missing or fails its integrity check, start-up rebuilds it from the replica, then the newest healthy snapshot. Anything damaged is moved aside, never deleted.
14
MCP tools for agents
4
independent backup layers
4
steps in the recovery chain
16
server tests, from recovery to search

Agents as a real user

The server speaks MCP over Streamable HTTP, with tools to list, search, read, create, update, trash and restore notes and projects. Agents read and write Markdown and can name a project by path, like Guitar / Songs. When Claude adds to a note, it uses an append mode so it doesn't rewrite what I wrote, and the note's history is always saved before an agent edit. Their changes appear live in any open browser, so I can watch a note fill in while Claude works.

Offline, and two tabs at once

The browser keeps the library in IndexedDB and queues edits in its own outbox when the server can't be reached, then sends them when it's back. Every save carries the version it was based on. If two tabs edit the same note from the same version, the later save wins, but the one it overwrote is kept in history marked as a conflict, so nothing disappears quietly.

Running it

  • Docker Compose runs Sonatelle and Redis, restarts both after a reboot, and only listens on 127.0.0.1.
  • Tailscale can serve it over HTTPS to just my own devices, so nothing has to be open to the internet.
  • An access token, rate limits on writes, request size limits and a strict, hashed Content Security Policy guard the API.
  • Structured logs, Prometheus metrics, a health check and a graceful shutdown that finishes its backup before exiting.