Getting started

Four steps, about two minutes. You need macOS or Linux and Node.js 18 or newer.

1. Install

npm install -g @kleos-research/kaleidoscope

You get the kscope command and the engine built for your platform.

2. Activate your key

export KALEIDOSCOPE_API_KEY=<your key>
kscope activate

Look for "entitled":true and a fragment of your key. activate stores the key, so new terminals find it without the export.

No key yet? Email contact@kleosresearch.xyz. To keep the key out of your shell, write it instead into the api-key file at the path kscope gate prints, at mode 600.

3. Give a project a memory

cd ~/your-project
kscope init

Expect output like this:

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: restart your agent, then ask it to search your memory.

The wired line names the editors init found on this machine; it skips any whose configuration directory does not exist. The steps under it name the new vault your-project, after the project folder, which is the profile the wiring starts each editor with — init writes it for you, so there is nothing to run afterwards. The first init on a machine also names it default.

To create the vault and write no configuration, run kscope init --no-wire. Connect an editor lists what lands where, per editor.

4. Restart your agent, then talk to it

Your agent now has two tools, search and remember. You never call them yourself.

Ask it what you decided about a design last week. Tell it you prefer a particular approach. It picks the tool.

If it does not seem to know its memory is there, give it the skill — a short file that teaches it when to read and when to write. Otherwise see Troubleshooting.

Removing it

Delete .kaleidoscope from a project to delete that project’s memory. npm uninstall -g @kleos-research/kaleidoscope removes the command and leaves every vault alone. Operations covers moving and inspecting a vault.