Profiles and vaults

A vault is one memory store: a directory at a path you chose. A profile is a name for one — an absolute root, the three identifiers inside it, and the durability. An editor or agent is started with a profile name; nothing else is.

Create a vault

cd ~/your-project
kscope init

init resolves the root, creates the vault there, and prints the path along with where the path came from. Resolution order:

Order	Root
1	KSCOPE_ROOT
2	.kaleidoscope/ under the repository’s main checkout
3	.kaleidoscope/ under the working directory

A root that is already a vault is reported and left exactly as it is. Add --no-wire to create the vault and touch no editor configuration.

To control the moment a vault records as its creation, name the root and an RFC 3339 instant. This form creates the vault and wires nothing:

kscope init /absolute/path/to/vault 2026-08-30T09:00:00Z

Durability is the last word on either form. process-local is the default and the only value any release accepts, so kscope init durable-local is refused before anything is written. What process-local promises is that a vault stays complete-or-absent across a process crash or a hard kill.

Name a vault

kscope init already writes a profile for the vault it creates, named after the project folder, so a project set up that way needs nothing here. Reach for these when you want a second name — a vault you created with --no-wire, or one you want to address under a name of your own:

kscope profile import work ~/your-project/.kaleidoscope

Command	Use it when
profile import NAME ROOT	The vault exists. Reads its identity and writes the profile.
init-profile NAME ROOT CREATED_AT	You want the vault and the profile in one step.
profile create NAME ROOT WORKSPACE_ID PRINCIPAL_ID JOURNAL	You already hold the identifiers. They are verified against the vault.

The profile named after the project folder, your-project for ~/your-project, is the one the wiring starts your agent with. kscope init creates it; kscope init --no-wire does not, because it wires no editor to name it. Until it exists, anything started with --profile your-project refuses with profile does not exist.

The first kscope init on a machine also writes default, naming that first vault, for commands and older editor entries that name default. A project set up by an earlier version stays on default until you move it. kscope init --shared uses a shared profile, naming .kaleidoscope in your home folder.

If init-profile commits the vault and then fails to write the profile, it keeps the vault and prints the kscope profile import command that finishes the job.

None of the three creates or relocates vault data, and none stores a secret. A profile is a pointer.

List, inspect, remove

kscope profile list
kscope profile show your-project
kscope profile launch your-project
kscope profile remove work

Command	Prints
profile list	Every profile on this machine, each validated against its vault as it is read.
profile show NAME	One profile: root, workspace, principal, journal, durability.
profile launch NAME	The launch descriptor an editor entry is made of — this executable’s absolute path, mcp --profile NAME, and the tools search and remember. No vault coordinates, no key.
profile remove NAME	The removal. The vault the profile pointed at stays on your disk.

Deleting a profile, naming a different one, or reinstalling Kaleidoscope leaves every byte of every vault where it was. Getting rid of the memory itself is a separate act; see Operations.

When no profile is named

There is no active profile and no kscope profile use. mcp and call resolve a vault by the same three rules init uses. Print the address they will arrive at before you rely on it:

kscope where

A resolved root that is not a vault is refused by both, naming the path and where the path came from. They never create one.

Binding a profile to an account

profile account show, bind and unbind are not on this executable. The only account-shaped command that ships is kscope activate, which stores your key; the rest is on the account page.