Connect an editor or agent

kscope init creates the project’s memory, names it after the project folder, and writes the entry each editor needs to find it. One command:

cd ~/your-project
kscope init

Each entry starts the engine with --profile your-project, the profile named after the folder. init writes that profile along with the vault, so there is nothing to run afterwards. The first init on a machine also writes a default profile naming the same vault, for commands that name default.

To use one vault for every project instead, run kscope init --shared. It wires the project to .kaleidoscope in your home folder, under the shared profile, and creates no vault in the project. kscope init --vault NAME wires it to the vault an existing profile names. A later kscope init keeps either choice.

Restart your editor. Until you do it is still running with the configuration it started with.

What you should see

kscope: created vault ~/your-project/.kaleidoscope (repository default)
kscope: wrote /.kaleidoscope/ to a new ~/your-project/.gitignore
kscope: wired codex, claude-code, cursor, opencode
kscope:   create the default profile, which names this vault, for the commands and older entries that name default
kscope:   create the your-project profile, which this project's agents open
kscope:   register the MCP server with codex
kscope:   agents for codex
kscope:   skill for codex
...
kscope: restart your agent, then ask it to search your memory.

One line per step, and a named failure for any step that could not be written. init wires an agent only when that agent’s configuration directory already exists on this machine. If it finds none it writes an AGENTS.md, which most other agents read, and says so.

What lands where

Agent	MCP entry	Instructions	Skill
Claude Code	~/.claude.json, under this project	a marked block in CLAUDE.md	.claude/skills/use-kaleidoscope/
Codex	.codex/config.toml	a marked block in AGENTS.md	.agents/skills/use-kaleidoscope/
Cursor	.cursor/mcp.json	.cursor/rules/kaleidoscope.mdc	none
OpenCode	opencode.json	a marked block in AGENTS.md	.agents/skills/use-kaleidoscope/

Every MCP entry applies to this project only. Claude Code keeps its entry for a project in ~/.claude.json; the others are files in the project. Instructions and skills go in the project too, where git carries them into the worktree or clone your agent works in.

The entries are written for every existing checkout of the repository, the main one and each worktree. In a worktree you make later, kscope where says to run kscope init there. .codex/config.toml, .cursor/mcp.json and opencode.json name this machine’s kscope, so init adds each to the project’s .gitignore, with its receipt and backup.

A project set up by an earlier version keeps its user-wide entries and the default profile. kscope init says so, and names the command that gives the project its own vault.

Each file gets a receipt beside it — .kaleidoscope-owner.json for a host configuration, .kaleidoscope-instruction-owner.json for an instruction file or skill. A file that already existed is copied to <name>.kaleidoscope-backup first.

Nothing written carries a vault path, a provider key or an account credential. The entry names this executable, a profile, and the two tools search and remember.

Running it again

kscope init again is safe. A root that is already a vault is reported and left exactly as it is; the wiring is re-checked and repaired.

If a Kaleidoscope block no longer matches its receipt — you edited inside the markers, or wrote an entry by hand — that step stops and names the file. The other steps still run.

To create the vault and write no editor configuration at all:

kscope init --no-wire

--no-wire writes no profile for the project either, because it wires no editor to name it. If you wire one by hand later, Troubleshooting has the command that writes it.

Removing it

There is no disconnect verb on kscope, so remove the wiring by hand. Delete each of these with the receipt beside it:

• the kaleidoscope entry under your project’s mcpServers in ~/.claude.json, and under mcpServers in .cursor/mcp.json
• the kaleidoscope entry in opencode.json
• the block between the kaleidoscope-manager markers in .codex/config.toml
• the marked block in CLAUDE.md or AGENTS.md
• .claude/skills/use-kaleidoscope/, .agents/skills/use-kaleidoscope/ and .cursor/rules/kaleidoscope.mdc

npm uninstall -g @kleos-research/kaleidoscope removes the command itself.

None of that touches your memory. An entry pointing at a vault that no longer exists is harmless, and kscope init writes the wiring back. Operations covers moving, backing up and deleting a vault.