Skip to content

Knowledge ​

Knowledge gives every AI agent on your cluster the same memory of what works. It is on by default on every node and needs no setup: Clusto registers its own MCP server in your coding tools, keeps a short managed section in their instruction files, lets agents propose lessons you approve, mirrors Claude Code memory per repository, and backs the whole agent setup up with versions you can restore.

Open it from the navigation (Knowledge) or press F1 and run Go to Knowledge. The view has four cards: AI setup, Lessons, Agent memory, and Backups.

AI setup and backups act on the node the app is connected to. Lessons, Agent Docs, and memory are cluster-wide.

What happens on each node ​

Each node keeps itself configured. It checks its setup on start, after every knowledge change, and every few minutes, and repairs whatever drifted.

  • Notes vault. Every node gets a local Notes vault. It defaults to ~/.clusto/notes in the home of the node's default_session_user, so agents running as that user can read it. A vault that still lives in the daemon's data directory is moved there once. Files written into the vault keep the vault owner. An explicit user or local_dir on a vault is left alone. A node keeps every vault in whose Kept on scope it is; other vaults get no copy there (see Multiple vaults).
  • MCP server. Clusto registers an MCP server named clusto (command clusto mcp) in each installed tool: Claude Code (~/.claude.json), Codex (~/.codex/config.toml), and Gemini CLI (~/.gemini/settings.json).
  • opencode MCP server. opencode gets the clusto MCP server from the Clusto-owned plugin below, so opencode.jsonc is never rewritten. A clusto MCP entry you wrote yourself wins.
  • Waiting status. The ? waiting marker is wired for you: Clusto adds its own hooks to Claude Code's settings.json and writes the plugin ~/.config/opencode/plugins/clusto.js for opencode (first line // clusto:managed, rewritten by Clusto). Gemini CLI gets hook entries in ~/.gemini/settings.json and GitHub Copilot CLI a Clusto-owned ~/.copilot/hooks/clusto.json. Codex reports waiting itself; Cursor has no hook that fires while it waits, so it uses the copyable instructions. Your own Claude Code and Gemini CLI hooks are never touched, and a file at the plugin or Copilot hooks path that is not Clusto's is reported as an error and left alone.
  • Local access file. The daemon writes ~/.config/clusto/local-daemon.toml (mode 0600) for the session user, so clusto mcp and clusto lessons work from any terminal with no flags or token.
  • Managed instruction section. Each installed tool's user instruction file (CLAUDE.md, Codex AGENTS.md, GEMINI.md, and so on) gets a section fenced by two HTML comment markers named clusto:knowledge:start and clusto:knowledge:end. It tells the agent how to use the Clusto tools and lists the approved global lessons. Clusto rewrites only that section; the rest of the file is yours. Do not write the markers into your own text: Clusto treats whatever sits between a start and an end marker as its section and replaces it. Agent Docs ignores the section when it compares or imports files and keeps it when it writes them.
  • Agent Docs sync. Your user-scope Agent Docs (global instructions, skills, subagents, and commands) are kept in step with the files of the node's agent account, in both directions. An edit made on the node is captured, a new or deleted skill, subagent, or command is picked up, and every saved item is written into each installed tool's folder where it is missing or out of date. Project scope stays manual. See Agent Docs.
  • First-run import. If the cluster tracks no user-scope Agent Docs yet, the node's existing global instructions, skills, subagents, and commands are imported into Agent Docs automatically. This happens once, and only on a node in two-way sync mode; deleting everything later does not re-import.

The AI setup card lists each check (vault, access file, MCP per tool, instruction section per tool, Claude Code waiting status, Codex waiting status, opencode waiting status, opencode MCP server, Gemini CLI waiting status, GitHub Copilot CLI waiting status, Agent Docs sync, memory, backups) with its state. The Agent Docs sync row counts items tracked, captured, newly tracked, deleted, files written and removed, needs review, not synced, and errors. Fix now re-runs the setup; F1 has the same action as Re-run AI setup on this node.

Turning it off ​

Select Turn off on the AI setup card, or set it in the node's config.toml:

toml
[knowledge]
enabled = false

This is per node. Turning it off also removes the Claude Code and Gemini CLI waiting hooks, the Copilot hooks file and the opencode plugin together with the rest of the setup. Turn on in the same card enables it again.

To keep Knowledge on but change how a node takes part in Agent Docs sync, set agent_sync to "two_way" (default), "receive_only", or "manual". The same choice is the Skills and instructions sync select on the AI setup card (shown while knowledge is on) and, while the Knowledge view is open, the F1 actions Agent sync on this node: Two-way, ... Receive only, and ... Manual:

toml
[knowledge]
agent_sync = "manual"

Receive only writes the cluster's items to the node and sends nothing back. Manual does nothing automatically; you move items from Agent Docs. Manual suits a machine with a separate login, such as a work laptop on a company Claude account. See Sync modes.

Node Doctor ​

Settings > Node Doctor (System group) shows the AI setup of every cluster node in one place, so you do not have to connect to each node to repair it.

  • Each node is a row with a status: All Good, N Issues, Off (Knowledge is turned off there), Offline or Error. A peer that cannot be reached shows its error in the row.
  • Expand a row to see that node's checks, the same list as the AI setup card.
  • Fix repairs one node. Fix all repairs every node, and Check again re-reads them.
  • A This device row at the top checks the notifications of the device you are on: system notification permission (Fix asks for it; if it is blocked, allow Clusto in the OS settings), alert popups (Fix turns them on), and alert sound, Android background checks and muted sessions, which are shown as choices rather than issues. Send test notification raises a sample alert through the same path a waiting agent uses. Fix all (and the F1 action) fixes this device too.
  • The card footer has Copy setup instructions for tools Clusto cannot wire itself, such as Cursor.

F1 has Open Node doctor and Fix agent setup on all nodes. A session (agent) credential can only read its own node's setup; fixing another node needs your account in the app or the node admin token.

MCP tools ​

The clusto MCP server gives agents these tools:

ToolDoes
clusto_lessonsApproved lessons for the current repository and global ones
clusto_propose_lessonProposes a lesson for your review
clusto_notes_vaultsLists the Notes vaults this node keeps
clusto_notes_searchFull-text search over a Notes vault
clusto_notes_readReads a note
clusto_notes_listLists notes in a vault
clusto_notes_writeCreates or updates a note

The four note tools accept an optional vault (id or name from clusto_notes_vaults). Without it they use the node's first vault. An agent can only reach vaults the node it talks to keeps. | clusto_list_tasks | Lists the cluster's scheduled tasks with schedule, last exit code, next run and pause window | | clusto_get_task | Reads one task in full, by id or exact name | | clusto_task_runs | Recent runs of a task with exit status and output tail |

The task tools are read-only. Agents change tasks only through the clusto task CLI, so a scheduled run is never rescheduled or fired without you asking.

ToolDoes
clusto_timer_statusThe running time-tracking timer, today's entries and the time projects
clusto_timer_startStarts a timer, stopping the account's running one
clusto_timer_stopStops the running timer

The timer tools act on time tracking, and agents use them only when you ask.

Lessons ​

Agents call clusto_propose_lesson after you correct them or after a fix attempt fails. A proposal does nothing until you approve it; approval is the trust boundary. Text that looks like a secret is refused.

Pending proposals appear at the top of the Lessons card:

  • This repository approves the lesson for the repository it came from.
  • Everywhere approves it globally. Global lessons are written into the managed instruction section of every tool on every node.
  • Choose nodes... next to the approve buttons approves the lesson but limits it to the nodes and OS accounts you tick.
  • Drop discards it. Approved lessons can be dropped the same way.

An approved lesson reaches every agent on every node unless you limit it. The Limit button on an approved row opens the same node and OS account picker, and the row then shows where it applies (for example "on 2 nodes" or "for daniel"). A limited lesson still syncs to every node, but agents on the other nodes and accounts never see it. Limiting is for lessons that name something private to one machine or account.

The same from the CLI:

bash
clusto lessons pending                      # proposals waiting for review
clusto lessons approve <id> [--global]      # this repository, or everywhere
clusto lessons drop <id>                    # proposed or approved
clusto lessons list [--repo <path>]         # approved lessons (default: current directory)
clusto lessons propose "<title>" "<body>" [--repo <path>]

Agent memory ​

Claude Code keeps per-project memory in ~/.claude/projects/<path>/memory. Clusto mirrors it per repository, keyed by the git remote, so the memory follows the repository across nodes, clones, and folder renames. The Agent memory card lists each repository and its file count.

  • MEMORY.md is Claude's own index and is not mirrored. When Clusto writes a memory file into a checkout, it adds an index line for it.
  • Files that look like secrets are not synced.
  • Folders whose checkout no longer exists are not mirrored.

Backups ​

Cluster replication is not a backup: a bad save replicates everywhere. The Backups card stores versions of Agent Docs, assets, variables, lessons, memory, and Markdown notes off the cluster, and restores any of them.

TargetWhereHistory
Clusto cloud (default)Your Clusto accountFree: 10 versions / 50 MB. Pro and Team: 100 versions / 500 MB. Oldest versions are pruned.
Git repositoryA folder on the node, default ~/.clusto/backup (the folder field has a browse button that picks a folder on the node), with an optional private remoteFull git history. Commits only when something changed.
S3The bucket of the first vault with sync on, under the .clusto-backup/ prefixKeeps the configured number of versions
OffNo backupsNot recommended
  • Cloud backups are encrypted in the app with your cloud-sync passphrase before upload, so the daemon never holds cloud credentials and the cloud stores only ciphertext. They run from the app while you are signed in with sync unlocked.
  • Git and S3 backups run on the node about once an hour when something changed. Git commits and pushes as the account that owns the folder.
  • Because Agent Docs sync tracks every skill, subagent, and command, including binary skill files, these backups cover your whole agent setup.
  • Snapshots include the notes of every vault the node keeps, tagged by vault. Notes larger than 1 MB are skipped, and a very large vault carries only its newest notes (up to 16 MB).

Back up now forces a backup (F1: Back up agent knowledge now). Versions lists stored versions; Restore replaces the knowledge records cluster-wide with that version and overwrites the notes contained in the backup. Notes that are not in the backup are kept. Notes are written only into vaults the restoring node keeps.

The target can also be set in config.toml:

toml
[knowledge.backup]
target = "git"                 # cloud | git | s3 | off
git_dir = "~/.clusto/backup"   # git: repository folder
git_remote = "git@example.com:me/agent-backup.git"   # git: optional private remote
s3_prefix = ".clusto-backup"   # s3: key prefix inside the first synced vault's bucket
keep_versions = 30             # s3: versions kept

clusto doctor ​

clusto doctor [--fix]

Shows this node's AI setup, the same checks as the AI setup card. --fix repairs what is missing. Before the AI setup, the command also checks the local daemon install and prints a diagnosis; see the CLI reference. If the daemon cannot be reached, the AI setup part prints AI setup: not checked - <reason>. Inside a session that holds a limited session credential (any session not running as the daemon's own account), --fix shows the checks without repairing them: use Fix now in the app or pass the node admin token with --token.

Command palette ​

CommandDoes
Go to KnowledgeOpens the Knowledge view
Re-run AI setup on this nodeRepairs MCP registration, the managed section, the waiting-status hooks, and the access file
Open Node doctorOpens Settings > Node Doctor
Fix agent setup on all nodesRepairs the AI setup on every cluster node
Back up agent knowledge nowRuns a backup to the configured target
Refresh knowledgeReloads lessons, memory, and setup state

All but Go to Knowledge appear while the Knowledge view is open.

Clusto - remote AI coding agents over WebSocket.