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 [notes] user or local_dir is left alone.
• 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).
• 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.
• 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; deleting everything later does not re-import.

The AI setup card lists each check (vault, access file, MCP per tool, instruction section per tool, memory, backups) with its state. 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:

[knowledge]
enabled = false

This is per node. Turn on in the same card enables it again.

MCP tools

The clusto MCP server gives agents these tools:

Tool	Does
clusto_lessons	Approved lessons for the current repository and global ones
clusto_propose_lesson	Proposes a lesson for your review
clusto_notes_search	Full-text search over the Notes vault
clusto_notes_read	Reads a note
clusto_notes_list	Lists notes in the vault
clusto_notes_write	Creates or updates a note

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.
• Drop discards it. Approved lessons can be dropped the same way.

The same from the CLI:

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.

Target	Where	History
Clusto cloud (default)	Your Clusto account	Free: 10 versions / 50 MB. Pro and Team: 100 versions / 500 MB. Oldest versions are pruned.
Git repository	A folder on the node, default ~/.clusto/backup, with an optional private remote	Full git history. Commits only when something changed.
S3	The Notes bucket, under the .clusto-backup/ prefix	Keeps the configured number of versions
Off	No backups	Not 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.
• 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.

The target can also be set in config.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
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.

Command palette

Command	Does
Go to Knowledge	Opens the Knowledge view
Re-run AI setup on this node	Repairs MCP registration, the managed section, and the access file
Back up agent knowledge now	Runs a backup to the configured target