---
url: https://clusto.app/docs/knowledge.md
description: >-
  Zero-config agent knowledge - an MCP server, approved lessons, mirrored Claude
  Code memory, and versioned backups of your whole agent setup on every node.
---

# 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](/notes). 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](/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`:

```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:

```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.

| 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](/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`:

```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 |