Troubleshooting

Every heading below is a symptom. Find the one that matches what you saw.

Two commands answer most of it, and neither needs a key:

kscope where
kscope gate

Your agent does not list search and remember

Restart the editor first. Most read their configuration once, at startup, so an editor that was running during kscope init has not seen it.

Then check the vault and the profile the editor starts:

kscope where
kscope profile list

profile list must show the profile the editor starts with "valid":true: the one named after the project folder, or default for a project set up by an earlier version. The tools an agent sees are exactly search and remember — anything else is another server.

Your editor says profile does not exist

kscope init creates the project’s profile along with the vault, so a project set up that way does not hit this. You will see it when the vault was created with kscope init --no-wire, which writes no profile because it wires no editor. Write the one your editor’s entry names, here your-project:

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

Restart the editor.

A command refuses with E_NO_KEY

kscope: this build requires an alpha entitlement and no key was found.

Install your key, then run the command again:

kscope activate <KEY>

Your vault is untouched by the refusal. No key yet? Email contact@kleosresearch.xyz.

	Commands
Need a key	mcp, call
Work without one	where, schema, model, gate, vault-preview, vault-verify, vault-migrate

Your agent is reading the wrong project’s memory

kscope where

root_source says how that vault was chosen. The common answers:

root_source	Means	Fix
environment	KSCOPE_ROOT is set	unset it, or point it at the vault you want
repository_default	the .kaleidoscope in this checkout	run from the project you meant
vault_ancestor	a vault in a parent directory	create one in this project with kscope init

An editor started with --profile NAME uses that profile’s root and ignores all three.

kscope init wired no editor

It wires an agent only when that agent’s configuration directory already exists on this machine. Finding none, it writes an AGENTS.md, which most other agents read, and says so.

Install the editor, then run kscope init again. To create a vault and write no configuration at all, run kscope init --no-wire.

One wiring step says FAILED

kscope:   claude for claude-code — FAILED: host configuration conflict: the
manager-owned instruction block has been hand-edited and no longer matches its
owner receipt

Something inside a marked block changed after kscope init wrote it. The other steps still ran. Delete that block and run kscope init again.

OpenCode configuration is refused

OpenCode has two configuration shapes, stable-v1 and beta-v2. kscope init adopts the one already in your file and never rewrites stable into beta. When both are present it stops and asks for manual review.

Remove the duplicate Kaleidoscope entry from the project’s opencode.json, then run kscope init again.

There is no kscope login

kscope has no login, logout, or account verb. Your key is what entitles the machine, and kscope activate puts it in place.

Do not delete or recreate a vault over this. Your memory never depended on an account.

The install left you without kscope

You need macOS or Linux, on Apple Silicon or x86_64, with Node.js 18 or newer. Windows is not supported yet — Platforms.

If kscope installed but will not launch, nothing is signed for release, so an operating-system refusal to run unsigned code is the likely cause. If it launches and then refuses, read the key section above.

Your agent has the tools and never uses them

The tools are there; nothing has told the agent when to reach for them. Install the skill and the instruction block: give your agent the skill.

Before you share diagnostics

Strip local paths, account identifiers, provider keys, tokens, queries, results and memory content out of anything you send.

A command that resolved a vault rather than being told one prints that absolute path on stderr, unprompted. Cut that line too.