Operations

Your memory is one directory: .kaleidoscope, inside your project, or in your home folder if you set the project up with kscope init --shared. Everything on this page works on that directory, and none of it needs an account.

To find out which vault a project resolves to, run kscope where — see Diagnostics.

Back it up

Close the editors and agents using the vault, then copy the directory whole.

cp -a ~/your-project/.kaleidoscope ~/backups/your-project-vault

A partial copy is not a vault.

Move it to another machine

Put the directory where you want it, then name it and check it.

kscope profile import restored ~/your-project/.kaleidoscope
kscope vault-verify ~/your-project/.kaleidoscope

profile import reads the identity out of the vault and writes a profile called restored. Start an agent against it with --profile restored. vault-verify prints "status":"complete" when the copy is whole.

Do not run kscope init on a vault you moved. It leaves the vault alone, but it rewrites that project’s editor wiring.

Delete a vault

Two commands. Preview first.

kscope vault-preview ~/your-project/.kaleidoscope

You get an inventory — entries, bytes, what is canonical and what is rebuildable — and a confirmation_token. Pass that token back:

echo '{"confirmation_token":"TOKEN"}' | kscope vault-delete ~/your-project/.kaleidoscope

The token belongs to the root you previewed. Point it at another vault and you get confirmation token does not match this vault root and path, and nothing is deleted.

Deleting the vault deletes the memories in it. CLAUDE.md, AGENTS.md, the Cursor rule and the skill directories stay where they are; remove those separately.

Update, pin, or roll back

What you want	Command
the current release	npm install -g @kleos-research/kaleidoscope
a version you name	npm install -g @kleos-research/kaleidoscope@<version>
the version you had before	undo the vault upgrade first, below, then the same command, naming the older version

Restart your agents after you update. An agent that is already running keeps the old version until it restarts.

Release notes list what is current.

Upgrade a vault, or undo the upgrade

The first time kscope saves a memory into a vault in the older format, it first rewrites the vault in a newer, smaller one. If the copy of kscope your agents run is older, it saves nothing and says so instead: update, restart your agents, and save again. Searching never upgrades a vault. A vault in the new format cannot be opened by an older version, so going back to one takes a step of its own.

What you want	Command
upgrade a vault now, without saving	kscope vault-upgrade <ROOT>
see what undoing the upgrade would drop	kscope vault-rollback <ROOT>
undo it	the --confirm command that kscope vault-rollback <ROOT> prints

kscope vault-rollback <ROOT> changes nothing. It lists the memories that changed since the upgrade and what undoing it does to each, and prints the exact command that does it. That command refuses if anything was saved in between. It also lists your other vaults, because every project on the machine runs the same kscope, and the steps that follow.

The upgrade keeps the old vault as one file beside the new one until the 10th save, or 3 days after the first save, whichever comes first. After that the upgrade cannot be undone. kscope where shows how long is left.

Remove Kaleidoscope

Four separate things. Removing any of them leaves your memory where it is.

What	How
the package	npm uninstall -g @kleos-research/kaleidoscope, then delete the copy your editors run, ~/.kaleidoscope/bin/kscope
an editor’s connection	delete the Kaleidoscope entry from that editor’s configuration file
the agent instructions	delete the marked block from CLAUDE.md or AGENTS.md, then .cursor/rules/kaleidoscope.mdc and the use-kaleidoscope skill directories
the vault	preview and delete it, above

Every block kscope init writes sits between kaleidoscope-manager markers, with a receipt file beside it. Removal is by hand: kscope has no disconnect verb.

Encrypted vaults on macOS

Encrypted vaults, kept inside an encrypted disk image, are deprecated. kscope can no longer create, import, list or delete one. What remains is there so you can move an encrypted vault you already have to a plain one.

Task	Command
open, close	kscope vault-open, kscope vault-close
recover with the key	kscope vault-recover
export the device package	kscope vault-export-device

Each takes a repository path. The help text has the arguments, and the steps to move an encrypted vault to a plain one.