Appearance
Notes - Markdown vault with chat co-writing
The Notes view is a personal Markdown vault (an Obsidian-style alternative) built into the Clusto app. It gives you a file tree with a name filter and a source + live-preview Markdown editor. Any Claude, Codex, OpenCode, or OpenRouter chat can link notes or note folders from the vault as context, so you can talk about, organize, and co-write your notes.
Notes live in an S3-compatible bucket as the shared source of truth and are synced to a local directory on each node, so agents operate on real local files (fast, and Claude Code needs a real filesystem).
Every node now gets a local vault with no setup, rooted at ~/.clusto/notes in the default_session_user's home, and agents read and write it through the clusto MCP server - see Knowledge. A vault in the older ~/.hive/notes location is moved there automatically on daemon start.
You can keep more than one vault (for example Work and Personal) and choose which nodes keep each one - see Multiple vaults below.
Enabling the vault
Add a [[vaults]] entry to the daemon's config.toml on the node you connect to:
toml
[[vaults]]
id = "notes" # stable slug, unique in the cluster
name = "Notes"
nodes = [] # Kept on: node ids; empty = every node
enabled = true
bucket = "my-notes" # S3 bucket (sync is off without this)
endpoint = "https://s3.amazonaws.com" # omit for AWS; set for MinIO/R2/B2
region = "us-east-1" # many S3-compatible providers accept "auto"
access_key = "AKIA..." # falls back to AWS_ACCESS_KEY_ID env var
secret_key = "..." # falls back to AWS_SECRET_ACCESS_KEY env var
local_dir = "~/.clusto/notes" # default: ~/.clusto/notes of default_session_user (node-local)
user = "daniel" # root the vault in this OS user's home (node-local)
prefix = "" # optional key prefix inside the bucket
sync_interval_secs = 300 # background pull cadence (min 60)An existing single [notes] section is migrated automatically on load into a vault named Notes (id notes) with the same folder and bucket settings, so S3 keys and on-disk paths do not move. The default folder for a vault other than the first is ~/.clusto/vaults/<id>.
- Local-only is fine. With
enabled = truebut nobucket, the vault works entirely locally (editor, agents); it just never reaches S3. - Credentials. Keys may live in
config.tomlor be injected at runtime via the standardAWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEYenvironment variables (leaveaccess_key/secret_keyunset to use them).
Links and the vault
The daemon usually runs as root while the vault sits in a user's home folder, so the vault is kept confined to that folder:
- Vault location. A vault configured under the notes user's home must still resolve inside that home. If the vault folder, or a folder on the way to it, is a symbolic link that leads outside the home, the daemon refuses to use it and the error says to set
local_dirto the real directory. A link that stays inside the home is fine, and a vault you configured outside any user's home is used as configured. - Links inside the vault. A link is followed only while it stays inside the vault. A link that leads out of it, an absolute one included, is refused as "path escapes vault root". Links are not listed in the tree and are skipped by search.
- Hard links. A note with a second name (a hard link, possibly to a file outside the vault) is not read or copied, is skipped by search, and a save that has to read it for the conflict check is refused. Renaming, copying or creating folders in the vault never re-owns a file with more than one name: it stays as it was and a warning is logged.
- Copying a folder. A link inside a copied folder, or a file with more than one name, makes the copy fail rather than copy what it points at. Copying a folder into itself is refused.
- Sync. A note that is a link or hard link is skipped by sync push. It is kept in the sync state and not treated as deleted, so other nodes keep their copy.
Ordinary notes are unaffected; these checks only matter if something in the vault was linked to a file elsewhere on the machine.
Configuring from the app
You don't have to hand-edit config.toml. The Notes view has a settings gear (top right) that opens a Notes vault settings dialog for the current vault - the same fields as above (name, enable sync, local directory, bucket, prefix, endpoint, region, access/secret keys, sync interval, and the Kept on node checklist). Saving writes that vault's [[vaults]] entry to the connected node's config.toml and takes effect without a restart. When the vault isn't configured yet, the "vault not configured" hint also offers a Configure vault button that opens the same dialog.
Saving also replicates the shared S3 settings to the nodes that keep the vault (see Cluster replication below), so you only configure the vault once and every node in its scope can serve it - no need to repeat the settings on each node.
Per-node directory and user. The dialog has a Node picker (shown when the cluster has more than one node): choose a node to view and edit its local vault directory and OS user. These two fields are node-local - only the S3 settings replicate. The User home dropdown lists the node's OS user accounts; picking one roots that node's vault under the user's home directory (e.g. /home/<user>/.clusto/notes). This is useful when the daemon runs as root or via systemd but you want your notes in your own home directory. Leave it on Daemon user (default) to use the daemon process's home / data directory. A ~-prefixed or relative Local vault directory resolves under the selected user's home; an absolute path is used as-is. The field has a Browse button that opens a directory picker rooted on the targeted node, so you can pick an existing folder (or create one) instead of typing the path by hand.
The dialog never displays stored S3 secrets: once a key is saved it shows as "stored"; leave the field blank to keep it, type to replace it, or tick Clear to remove it. The dialog works at both desktop and phone widths.
A Test connection button in the S3 section checks that the saved configuration can reach the bucket (it builds the store and lists the bucket without changing anything) and reports the object count or the exact error. It uses the saved config, so save any edits before testing.
If no vault is configured, the Notes view shows a "vault not configured" hint.
Preferred serving node
The node selector above the vault chooses which online cluster node serves Notes. Clusto remembers the preferred node on this device and routes the entire Notes workflow to it: listing, reading, editing, search, file operations, settings, manual sync, and the S3 connection test. Choose Use connected node to clear the preference and return to the daemon the app is connected to.
If the preferred node is offline, Clusto shows an Offline badge and stops Notes operations. It does not silently fall back to another vault, so the app cannot show or modify a different node's working copy by surprise. Choose another online node or explicitly switch back to the connected node.
Multiple vaults
A cluster can hold several named vaults, for example Work and Personal, each with its own notes, folder, S3 settings and open tabs. Each vault is an entry in [[vaults]] (id, name, nodes, enabled, bucket, prefix, endpoint, region, access_key, secret_key, sync_interval_secs, plus the node-local local_dir and user).
In the app, a second vault needs Pro, Team or a trial (see Plan below). In a cluster with more than one node, the vault settings dialog also shows the Kept on checklist. The Notes view has:
- Vault switcher in the Notes toolbar picks the current vault. Each vault keeps its own open tabs.
- New vault creates another vault. It starts kept only on the node that created it.
- Vault settings (the gear) has the name, S3 prefix and connection, the Kept on checklist, and Delete vault. Deleting removes the vault from the cluster; local copies stay on disk.
- A vault that the node you are connected to does not keep shows a Not kept on this node hint. Connect through a node that keeps it, or pick another vault.
Kept on (scope)
Kept on chooses which nodes keep a copy of the vault. Empty means every node. The checklist is the same node picker other settings use (plugin nodes, agent doc nodes and forge standby nodes), and it is shown whenever the cluster has more than one node.
- Nodes outside the scope never receive the vault's bucket settings or credentials and never get a copy of its notes.
- A node that leaves the scope erases the vault's credentials at once and stops syncing. Its local files stay on disk; the app asks before you delete them.
- Give every vault its own bucket or credentials (at least prefix-scoped keys). If two vaults share one set of keys, a node that holds one vault's keys could read the other vault directly in S3.
Strict boundary
A node outside a vault's scope cannot reach the vault through another node either:
Notes requests forwarded from it are refused with "not available from the node you are connected to".
A node that keeps the vault accepts nothing else forwarded from it either: no terminal, chat turn, task, file explorer, git or plugin request. Those would run next to the vault, so only Notes requests (checked per vault) and plain status reads get through. A shared vault such as Work stays reachable.
It cannot rename, re-scope or delete the vault. Only a node that keeps a vault can change or delete it.
Live task and run updates respect the same scope: a task or run that belongs to a node that keeps the vault is not pushed to a node the vault leaves out.
Agents on it cannot pick up a key to the vault. A node left out of any vault's scope gives every session a limited credential that works only on that node, whatever account the session runs as. That covers chats, terminals, tasks and the
clustoMCP server other AI tools on the machine use (through the access file), so the MCP tools, skills and theclustoCLI there see only the vaults the node keeps.Chats follow the same line. A chat belongs to the node it runs on (or is pinned to). A chat of a node that keeps the vault never replicates to a node the vault leaves out, not even through a third node, and the left-out node cannot change, take over or delete it. When a node is left out, it deletes its local copies of such chats (only its own copies: the chats stay everywhere else). Its own chats still show on every node.
Use this for a work PC that runs a company AI: leave it out of the Personal vault's Kept on list and nothing on that PC can read your personal notes or the chats of your personal nodes through Clusto.
The limits:
- A terminal session or chat you open on a node that keeps the vault runs there with that node's access, so the boundary is the vault, not the whole node.
- The boundary covers Notes and chats. Other cluster data (agent docs, lessons, SSH connections, reports) still replicates to every node. For full separation of a work machine, give it its own cluster.
- A chat that has never run and is not pinned belongs to no node yet. It is not sent to a left-out node, but a copy the node already had stays until the chat runs. Chat history the node received before it was left out may already have been read; deleting the copy does not undo that.
- Workspace files a replicated chat wrote on the left-out node stay on its disk.
- A left-out node never hands the cluster token to a client, so the Clusto app there keeps only that node's own token, which reaches the vault only through the refusals above. An app that signed in there before the node was left out still has the cluster token in its saved profile, which any program on the machine can read: delete that profile and pair the app again.
- Someone with administrator rights on the left-out machine can read the daemon's own configuration, which holds the cluster token.
Plan
Personal includes one vault. Creating a second vault needs Pro, Team or a trial. If a plan lapses, existing vaults keep working; only creating another one is blocked. See Accounts & Licensing.
Agents and vaults
Agents on a node reach the vaults that node keeps. The clusto_notes_vaults MCP tool lists them. clusto_notes_search, clusto_notes_read, clusto_notes_list, clusto_notes_write, clusto_notes_move (move or rename, never overwrites) and clusto_notes_delete (a note or an empty folder), and the chat tools clusto_list_notes, clusto_search_notes, clusto_read_note and clusto_write_note, accept an optional vault (id or name). Without it, the node's first vault is used. See Knowledge.
From a shell, clusto notes vaults|ls|search|read|write|mv|rm does the same (--vault picks the vault; write takes --content, --file or standard input, and --base-sha256 to update an existing note). See CLI reference.
Using the view
- File tree (left): the whole vault, folders first. Click a folder to collapse/expand, a note to open it. Use the Collapse all / Expand all toggle in the tree header to fold or unfold the whole vault at once. On desktop the tree panel is hidden by default; collapse it with the panel button next to the filter box, and re-open it from the slim rail that takes its place on the left edge. That choice is remembered for the current app session and resets to hidden when the app restarts. On desktop, drag the handle on the tree's right edge to resize it (180-480 px); the width persists across restarts via
localStorage["clusto-notes-tree-width"]. - Row actions: right-click a row (desktop) or tap its kebab (
⋮, touch) for a context menu - open, new note in a folder, new folder inside a folder, collapse/expand that folder, collapse/expand all, rename, and delete. - Folder color: right-click a folder row or open its kebab menu and choose Folder color... (or run Folder color... from the
F1palette) to give the folder one of nine named colors, or clear it. The color shows on the folder's icon in the tree. - New creates a note (a
.mdextension is added if you omit one); parent folders are created as needed. - New folder (the folder button next to the tree's filter box, or right-click the tree background) creates an empty folder without a note in it. Use
/for nested folders; missing parents are created too, and the new folder's ancestors are expanded so it is visible right away. - Drag and drop (desktop): drag files from your OS onto a folder row to upload them into that folder, or onto the tree background to drop them in the vault root; the target is outlined while you drag. Drag a row onto a folder to move that note or folder there. Names that collide get the same
" copy"suffix a paste does, so a drop never overwrites an existing note, and uploads are capped at 25 MiB per file. Touch devices use the row menu's cut/paste instead (HTML drag is a pointer affordance). - Editor (center): a CodeMirror Markdown editor with a live preview. Toggle source / split / preview in the editor toolbar; the chosen mode is a per-device preference that persists across restarts. In split mode, drag the divider between the source and preview panes to rebalance them (20-80%); the ratio persists via
localStorage["clusto-notes-editor-split"]. The editor auto-saves a short delay after you stop typing (so the agent and S3 always see your latest words);Ctrl/Cmd+Sstill saves on demand. The editor and preview font size is configurable in app Settings → Notes → Font size (a per-device preference, synced with the rest of your UI preferences). The preview understands Obsidian-flavoured Markdown - see Obsidian-flavoured Markdown below. - Tabs: every note you open gets a tab above the editor; tabs and the active note are remembered per vault across restarts. Close one with its
Xor a middle-click. Right-click a tab (long-press on touch) for Close, Close others, Close tabs to the right, Close tabs to the left and Close all. Closing a tab whose note has unsaved edits asks before discarding them, once for the whole batch, and Cancel closes nothing. Focus moves to the nearest remaining tab on the right, else on the left. - Drop files into a note: dragging files from your OS onto the open note uploads them to the vault's
attachments/folder and links them at the cursor - images as![[attachments/pic.png]]embeds (which render inline in the preview), other types as[[attachments/report.pdf]]wikilinks. The note is marked dirty and auto-saves like any other edit. - Info panel (desktop): the panel button in the editor toolbar opens a right rail with the note's Outline (click a heading to jump), Backlinks (other notes that link here - click to open at the reference), and Tags (click to search the vault for that tag).
- Attachment previews: opening an image, audio, video, or PDF file from the tree shows a read-only viewer instead of the text editor; any other binary type shows an info card with a Download button (desktop only). The tree uses type-specific icons for these files.
- Inline images: a Markdown image whose path points at a file in the vault (
, relative to the note, or/-prefixed for vault-absolute) renders inline in the preview pane. Externalhttp(s)/data:image URLs render as usual. Attachments load on demand (capped at 25 MiB) and are never edited from the app - drop them into the vault folder or let the agent in a chat that has the vault linked manage them. - Name filter: the search box at the top of the file tree filters the tree to files and folders whose name matches; matching folders keep their ancestors visible. It does not search note contents.
- Chat: the toolbar Chat button starts a normal Clusto chat with the open note, or the vault, linked as context - see Chat about your notes below.
Open a note in a separate desktop window
In the native desktop app, use the active note's actions or press F1 to open that note in its own window. If the note has unsaved changes, Clusto first saves it and waits for confirmation from the daemon. A failed or conflicting save keeps the editor in the main window. Repeating the action focuses the existing window instead of opening another copy.
The separate editor keeps the selected serving node but does not replace the main window's remembered tabs, active note, or preferred node. This option is not available in the web or mobile clients. See Separate desktop windows for connection and lifecycle details.
On phones the two panes become a bottom switcher (Files / Editor); all surfaces respect the safe-area insets. The info panel is desktop-only. The header keeps the vault and node pickers on one row and moves Search, New note, Chat, Pull, Push and vault settings into its three-dot menu. The tab strip appears once two or more notes are open, the editor bar shows just the file name, and there is no line-number gutter. While the on-screen keyboard is up, the header, tabs and pane switcher hide so the note fills the screen.
Obsidian-flavoured Markdown
On top of GitHub-Flavoured Markdown, the preview renders the Obsidian syntax most notes rely on. Everything is rendered in the existing source / split / preview panes - there is no separate "live preview" editing mode.
- Wikilinks -
[[Note]],[[Note|alias]], and[[folder/Note]]link to another note, resolved the way Obsidian does (exact path first, then a unique basename match). Click one in the preview to open it; a link whose target doesn't exist is shown in red.[[Note#Heading]]jumps to a heading. In the source editor, typing[[pops up an autocomplete of every note in the vault. - Embeds / transclusion -
![[image.png]]embeds a vault image (or audio / video / PDF) inline, and![[Note]](or![[Note#Heading]]) transcludes that note's content into the current one. The embedded note's title links back to the source; embeds inside an embed degrade to plain links rather than recursing. - Tags -
#tag(including nested#area/topic) renders as a pill. Click it to open the full-text search seeded with that tag, or use the Tags section of the info panel. - Callouts -
> [!note],> [!warning],> [!tip], etc. render as coloured callout blocks. An optional title after the type (> [!info] Heads up) is used as the callout heading. - Math - inline
$E = mc^2$and block$$ ... $$are typeset with KaTeX. - Diagrams - fenced
```mermaidblocks render as Mermaid diagrams (loaded on demand; the diagram theme follows the app's light/dark setting). - Code highlighting - fenced code blocks are syntax-highlighted with highlight.js, with colours that follow the app theme.
Backlinks and tag search reuse the vault's native full-text search, so they work on every platform (including mobile) without any extra index.
Spellcheck
The source editor can spellcheck notes offline. Enable it in Settings → Notes → Spelling check and pick one or more languages (Czech, Slovak, English US/UK, German, Polish, Spanish, French). Checking runs entirely on the device with Hunspell dictionaries - note text never leaves the app, and a dictionary is only downloaded and loaded for the languages you select.
- Underlines - words rejected by every selected language get a red wavy underline in the source pane. A word accepted by any selected language is fine, so mixed-language notes work naturally.
- Fixes - click or tap an underlined word to get suggested corrections; picking one replaces the word in place. Suggestions from all selected languages are merged and ranked by closeness to the typed word.
- Personal dictionary - Add to dictionary in the same popup accepts the word everywhere from then on. Custom words are stored as a
clusto-*preference, so they ride along with cluster preference sync and account cloud sync. Ignore skips the word for the current session only. - What is skipped - code blocks and inline code, URLs,
[[wikilinks]],#tags, and identifier-like words (CamelCase, ALL-CAPS) are never checked.
The checker runs in a background worker, so even the large Slavic dictionaries (a few MB each) don't block typing; very large notes (over ~200 kB) skip checking entirely.
Find in a note
Ctrl+F (or Find in note in the F1 palette) opens a find and replace bar in the open note's editor. Enter or F3 jumps to the next match, Shift+Enter to the previous one, and Esc closes the bar. In preview-only mode the editor switches to split view first, since the bar lives in the source pane.
Full-text search
The Search button in the toolbar (or Ctrl+Shift+F) opens a standalone search dialog that looks inside every note in the vault - distinct from the sidebar's name filter, which only matches file and folder names.
- Query: split into words, and a line matches when every word is found on it. Case and diacritics never matter, so
smlouvefinds "smlouvě" andzlutyfinds "Žlutý". Each word matches anywhere inside the text, so part of a word, an identifier, or a path (main.rs) still works. Czech words of four letters or more also match their other forms:smlouvafinds "smlouvy", "smlouvě", and "smlouvou". Special characters are taken literally, never as a regex. - Words on different lines: when a note contains every word but never all on one line, it still shows up once, at the line that matches the most words.
- Results: one row per matching line, showing the line with every matched word highlighted and the file name and line number at the end of the row. Exact matches come first, then matches that ignored diacritics, then other word forms, then notes whose words are spread over several lines. Binary files, dotfiles, and dot-directories are skipped; a broad query is capped at 500 hits.
- Preview: selecting a result (single click, or the arrow keys) shows a few lines of surrounding context below the list, with the matched line highlighted.
- Open: double-click a result, press Enter, or use the Open button in the preview header to jump to the note with the cursor placed on the match and the line scrolled into view. On phones this switches to the editor pane.
Search runs natively on the daemon over the synced local vault, so it works on every platform - including mobile, where no external search binary exists.
The clusto_notes_search MCP tool, which agents use to search the vault, applies the same matching and ranking.
Command palette
Pressing F1 anywhere in the Notes view opens a command palette - a fuzzy-searchable list of every Notes action, mirroring the full-text search modal. Type to filter, navigate with the arrow keys, and press Enter (or click) to run the selected action; Esc closes it.
The palette only lists actions that are runnable right now: open-note actions (rename, delete) appear when a note is open, the S3 Pull/Push entries appear only when sync is configured, and folder collapse/expand entries reflect the current state. Close other note tabs, Close note tabs to the right and Close all note tabs act on the active tab and appear only when they would close something. Chat about notes starts a normal chat and links the open note (or the vault when none is open). Every row shows its current shortcut or Not set. Select the badge to assign or change the shortcut, or use its reset control to restore the default. See Command palette shortcuts.
Chat about your notes
Notes no longer has a separate agent pane, private agent transcript or its own chat type. Every Clusto chat can use the vault as context, and the chat keeps everything else a chat has: the shared provider and model picker, transcript, composer, streaming progress, permission controls, Stop action, rename, delete, persistence, resume, and cluster reopening. See Work with notes in Chats for the full behavior.
- Start from Notes. Select Chat in the Notes toolbar, use Chat about notes in the command palette, or use Discuss this note. Clusto opens the normal New chat dialog with the open note (or the vault, when no note is open) already linked as context. You choose the provider, model and workspace as for any chat, and the chat is a normal chat, not a vault chat.
- Start from Chats. Select New chat and link a note from the composer after it opens, or from a Notes view action as above.
- Link note files. In any chat, use Notes in the composer to search the vault and attach notes or whole note folders. They work like any other chat attachment: they appear as chips, stay linked until you remove them, and every turn sees them. The Notes and Browse buttons show whenever the chat's node has a vault configured, and are hidden otherwise.
- Browse and open. Use Browse in the composer to inspect the vault. Selecting a linked note opens it in the Notes editor, so you can move between the conversation and the source file.
- Share notes with every chat in a workspace. A note or note folder can be a workspace default, so every chat in that workspace sees it. See Workspace default context.
- Older Notes chats. Notes chats created before this change keep working. They run with the vault as their working directory, so the agent reads and edits vault files directly, and they stay in the Notes group of the Chats sidebar. Claude Notes chats use
acceptEditsand allow WebFetch and WebSearch; Codex Notes chats use workspace-write access with approval prompts disabled. No new ones are created. - Vault instructions (
AGENTS.md+CLAUDE.md). For agents that run in the vault, the daemon seeds anAGENTS.mdwith Notes co-writing guidance and a thinCLAUDE.mdthat links to it (@AGENTS.md) when they are missing. Existing files are never overwritten. Edit them to shape agent behavior; they sync like other vault files. - Live co-editing. A vault file watcher notifies the Notes editor when an agent changes a file. A clean open buffer reloads the change, while normal optimistic concurrency protects unsaved local edits.
Sync model
- Push on save. Saving (or creating/deleting/renaming) a note through the app uploads it to S3 immediately, independent of the poll.
- Per vault. Each vault syncs to its own bucket on its own interval, with its own
.clusto-sync.jsonmanifest, file watcher and last-sync time. - Periodic pull and push. Every
sync_interval_secs, each node lists the bucket and downloads any object newer than its local copy, then pushes its own local changes (and deletions) back up. This runs on every node whether or not a client is connected, so edits made on disk - for example by the Notes chat agent or a terminal session - propagate to S3 and the rest of the fleet without anyone opening the app. After syncing it notifies connected apps (the view re-lists, and a non-dirty open note re-reads). - Manual sync. When sync is configured, the Notes toolbar shows Pull (download remote changes now), Push (upload notes changed since the last sync now), and a Synced … ago indicator of the node's last successful sync. These trigger the same engine as the periodic poll without waiting for the next tick - handy to confirm a freshly-configured vault is actually reaching S3.
- Change tracking. A hidden
.clusto-sync.jsonmanifest in the vault root maps each note's path to the sha256 of the bytes last synced. Push consults it to upload only notes whose content actually changed and rewrites it afterward; per-save push, delete, and pull keep it current. It is an optimization only - a missing or corrupt manifest just makes the next push re-upload everything. - Folder colors live in a hidden
.clusto-folders.jsonfile at the vault root. It syncs like a note, so colors reach your other nodes and the bucket. If two nodes change colors between syncs, the newer file wins. - Conflict resolution is last-write-wins by modification time. Pull and push are symmetric: on pull a remote object only overwrites a local note when it is newer and its bytes differ; on push a locally changed note only overwrites its S3 object when the local mtime is strictly newer than the remote, so the background push never clobbers a newer remote edit (it leaves that for the next pull). Simultaneous edits of the same note on two nodes keep the newer one and lose the older edit - there are no conflict-copy files in this version.
- Deletions. A local delete is mirrored to S3 - both the app's explicit delete and a file that disappears on disk and was previously synced (the background push removes it from the bucket so other nodes drop it on pull). Deleting a folder removes the folder's object and every object beneath its prefix, so the notes inside it do not survive in the bucket and reappear on the next pull. Remote deletions are not propagated to a node's local copy (a node never deletes a note it didn't delete itself).
- Names with non-ASCII / reserved characters. Object keys are stored under their real UTF-8 names (a folder
Práceis the S3 keyPráce/...), so the bucket stays readable for any external S3 client (e.g. Obsidian sync plugins). Pull still percent-decodes keys before writing to disk, which keeps it compatible with objects written by earlier builds. - Self-healing of legacy encoded keys. Earlier builds stored keys in a percent-encoded form (
Pr%C3%A1ceinstead ofPráce), and older ones also wrote those encoded names to disk, re-encoding the%on every cycle (%C5%A0pajzka,%25C5%25A0pajzka). Sync repairs both automatically: pull moves a legacy encoded object to its real-name key (byte-identical, last-write-wins against any existing clean twin) and deletes the encoded one, while a stray local copy whose name decodes to an existing clean note is removed instead of re-uploaded. The whole bucket converges to clean UTF-8 keys within a sync cycle or two. A legitimately%-bearing filename (one whose decoded form is not a different existing note) is never touched.
Cluster replication
The vault data is shared through S3, but each node also needs the S3 settings (bucket, endpoint, region, credentials, enable flag, interval) to sync and serve it. Those settings are replicated to the nodes that keep the vault so notes stay reachable when the node you originally configured is offline.
- Configure once. Saving the settings on any node that keeps the vault stamps a write timestamp, persists them locally, and broadcasts the vault list to every peer (
PeerMessage::SyncVaults). Each node applies the shared fields to its own[[vaults]]entry and starts syncing the vault from S3. - Credentials only in scope. The list is sent per peer. A peer in a vault's Kept on scope gets the full entry; any other peer gets only the id, name, scope and timestamp, with no bucket settings or credentials. Such a stub never overwrites credentials a node already holds.
- Last-writer-wins. A peer only applies an incoming list when its timestamp is newer than what it already has, so an out-of-order or stale broadcast cannot clobber a fresher setting. A peer outside a vault's scope cannot rename, re-scope or remove that vault.
local_dirstays node-local. Only the shared S3 fields are replicated; each node keeps its own working-copy directory (default~/.clusto/notesfor the first vault,~/.clusto/vaults/<id>for others, under the node's vault user, or under<data_dir>when no user is set).- Catch-up on reconnect. A node that was offline when the settings changed receives the current vault list when it rejoins the cluster, then resyncs.
- Credentials live on the nodes that keep the vault. Because each of those nodes syncs independently, the S3 access/secret keys are stored in their
config.toml, so the vault stays available when any single node goes down. - Choose which node serves notes. Without a preference, the connected node serves Notes. A per-device preferred node, limited to nodes that keep the vault, routes Notes operations through the cluster to that node. Clusto requires the selected node to be online and never falls back to a different vault silently.
Wire protocol
Client → daemon (ClientMessage): ListVaults, CreateVault, DeleteVault, and the notes messages below, each of which carries a vault_id: ListNotes, ReadNote, ReadNoteBinary (base64 bytes + MIME for attachments and inline images), WriteNote (base_sha256 for optimistic concurrency), CreateNote, UploadNote (base64 bytes for a dropped attachment; exclusive, so an existing path errors instead of being overwritten), DeleteNote, RenameNote, CopyNote, CreateFolder, SearchNotes, GetNotesSettings / SetNotesSettings, SyncNotes (direction: pull / push / both), and TestNotesS3, and SetFolderColor (folder path, color or none). Every request carries an optional node_id; when present, the connected daemon forwards it to that serving node. A standalone daemon rejects an explicit remote target instead of falling back locally.
Daemon → client (ServerMessage): VaultList (the vaults the node keeps, plus the rest by name), VaultCreated, VaultsChanged, NoteList (vault_dir + flat FsEntry tree + last_sync_unix + folder_colors), NoteContent, NoteBinary (base64 data + mime), NoteSaved, NoteWriteConflict, NoteActionResult, NoteSearchResults, NoteError, NotesChanged (broadcast after a sync pulls remote changes; carries the vault_id), NotesSettings, NotesSettingsError, NotesSyncResult (per-direction change counts + last-sync time), and NotesS3TestResult. Routed responses echo the target node_id, and mutation and search replies also echo their request_id. The app ignores a delayed reply from a previously selected node, so changing the preferred node cannot replace the current vault state with stale data. Vault settings replicate to the nodes that keep each vault (PeerMessage::SyncVaults, last-writer-wins); each node keeps its own working copy and can be selected as the serving node. See Cluster replication above.
Limitations (v1)
- Last-write-wins only; no Obsidian-style conflict copies.
- No graph view, and no "live preview" inline-rendering edit mode - rich rendering happens in the preview pane (source / split / preview).
- Backlinks and tag listings reflect the vault as it exists at the moment the panel loads; they refresh when you reopen a note, not continuously as you type.
- The preview does not render raw HTML: HTML written in a note shows as text. Links stay live only when they are relative or use
http,https,mailto, ortel; a link with any other scheme (javascript:,data:, ...) shows as its plain label. - Attachment viewers are read-only. Add files by dropping them onto the tree or into an open note, or ask an agent in a chat with the vault linked to manage them. Inline-image refs must resolve to a file in the vault (or be an external URL).
- Chat co-editing is not a true three-way merge: if you type in the brief window between the agent writing a note and the editor reloading it, the next auto-save can hit a write conflict (resolve it with the editor's overwrite prompt).
- The vault file watcher binds the resolved vault directory and re-binds when that directory changes in settings; if a watcher fails to start, agent edits still reach the editor on the next periodic sync rather than instantly.