Kaleidoscope local memory runtime Usage: AGENT -- the whole surface an agent needs. Two verbs, one door. kscope call search read; one JSON request on stdin kscope call remember write; one JSON request on stdin kscope schema remember the write contract, before writing kscope schema [OPERATION] every operation this build has kscope schema --list the same list, as JSON Both resolve the vault from this directory. Name another one with `--profile`, which is what an editor or harness is started with: kscope call --profile search kscope call --profile remember Everything below is an OPERATOR command: setup, inspection and vault lifecycle, run by a person or an installer and not by the agent using the vault. OPERATOR -- what this build is kscope --help kscope --version kscope model kscope gate kscope activate [KEY] kscope licences kscope public-contract OPERATOR -- bring a vault into existence, and wire this machine's agents to it kscope init [process-local|durable-local] [--no-wire] kscope init --shared kscope init --vault kscope init [process-local|durable-local] kscope init-profile [process-local|durable-local] OPERATOR -- profiles, a named non-secret pointer to one vault kscope profile create [process-local|durable-local] kscope profile import [process-local|durable-local] kscope profile list kscope profile show kscope profile remove kscope profile launch OPERATOR -- which vault a command that names none resolves to kscope where kscope where --root-only OPERATOR -- maintain a local vault kscope vault-migrate kscope vault-upgrade kscope vault-rollback [--confirm ] kscope vault-verify [--cross-backend] kscope vault-preview kscope vault-delete OPERATOR -- encrypted repository vaults, deprecated: removed in the next release kscope vault-open kscope vault-close kscope vault-recover kscope vault-export-device To move an encrypted vault to a plain one: stop the agents that use it; open it with vault-open, or with vault-recover on a machine whose Keychain lacks it; copy the entries of the .kaleidoscope folder in to a new folder, leaving out volume metadata such as .fseventsd, .Spotlight-V100 and .Trashes; close it with vault-close; the copy is not encrypted, so make git ignore it before it enters : add the line .kaleidoscope/ to the .gitignore in unless it is already there; move the copy into as its .kaleidoscope folder; check that folder with kscope vault-verify; then remove .kaleidoscope.sparsebundle, .kaleidoscope.vault.json and the Keychain item com.kleos.kaleidoscope.vault. OPERATOR -- run an engine for an agent, addressed three ways kscope mcp --profile kscope call --profile kscope mcp [process-local|durable-local] kscope call [process-local|durable-local] kscope mcp [process-local|durable-local] kscope call [process-local|durable-local] NOTES Addressing. The two engine commands take the four ids or none. Naming none resolves KSCOPE_ROOT, else `.kaleidoscope/` under the repository's main checkout, else under the working directory; the vault's own workspace record supplies the rest, and KSCOPE_WORKSPACE, KSCOPE_PRINCIPAL and KSCOPE_JOURNAL override that record field by field. Arguments win completely: an invocation naming the four ids never reads the environment. A resolved root that is not a vault is REFUSED, naming the path and where the path came from. They never create one: `kscope init` is the only way a vault comes into existence. A resolved root that is ALREADY a vault is refused too and nothing there is touched, because a second init would mint a second workspace inside it; durable-local on a fresh root is refused before any effect, so it is asked for rather than defaulted to. Init also ensures the repository ignores the vault: unless the repository's .gitignore already holds the vault's own rule, anchored or not, one commented rule is APPENDED, never reordering or rewriting the file. A different rule that happens to cover the vault is not recognised, so the file can gain one redundant line. Wiring. The resolved form does not stop at the vault. A harness counts as present only when the configuration directory the harness itself creates is already there, so nothing is written for a tool this machine does not run. For codex, claude-code, cursor and opencode it registers this executable as an MCP server for this project only (Claude Code's local scope in .claude.json; the project's .codex/config.toml, .cursor/mcp.json and opencode.json), writes the instruction file that harness reads, and installs the memory skill. Cursor has no skill directory and gets its rule file alone. When no harness is detected AGENTS.md is written anyway, because it is the one convention every harness reads and the alternative failure is silent. Each step is named on stderr and repeated in the wiring field on stdout; a step that fails is reported without failing the command, because by then the vault exists and a non-zero exit would send the reader to look at the wrong thing. Re-running init is how a harness installed later gets registered, so an init refused for an existing vault still wires and still exits 0. Which vault the agents open. Each project's agents open that project's own vault, through a profile named after the project folder, which init creates (and repoints, when the vault it named was deleted and made again). The first init on a machine also creates the default profile, naming that first vault, for the commands and older entries that name it. `--shared` wires this project's agents to the shared vault instead: .kaleidoscope in your home folder, a vault of its own under the shared profile, made on first use. `--vault ` wires them to any existing profile's vault. Neither creates a vault in the project, and a later init keeps that choice. A project whose agents already use the vault the default profile names, through the user-wide entry an earlier kscope wrote, stays on it, and init names the command that moves it. Every harness is registered in every existing checkout of the repository, the main one and each worktree, since they share one vault, and Claude Code also in the subfolder init ran in; in a worktree made later, `kscope where` says to run init there. The project's .codex/config.toml, .cursor/mcp.json and opencode.json name this machine's engine, so init appends a .gitignore rule for each, covering its receipt and backup too, and a teammate never receives them. A user-wide entry an earlier kscope wrote is kept, and init and `kscope where` warn which folders still open its vault: every folder with no entry of its own. `kscope init` in a folder gives it its own. An npm install registers a copy of itself, kscope in .kaleidoscope/bin under your home directory, rather than its own path, which npm may delete. A newer release of kscope, however it was installed, replaces an older copy when it runs one of the two engine commands; a build from source never does. init from npm installs its own engine there even over a newer one, which is how to roll the agents back. `kscope where` reports both versions. The copy is not part of the home vault: vault-preview does not count it and vault-delete leaves it where it is. The way back. The upgrade to format 2 keeps the vault's old database as one file beside it, until 10 saves or 3 days after the first save, whichever comes first; the save that makes it due deletes it. `kscope vault-rollback ` changes nothing: it says whether the vault can go back, which memories that drops (titles are the vault's own text, shown as data), and the exact command that does it, `--confirm ` with the vault's head commit, which refuses if any save landed since. Ask the person before confirming. kscope is one engine per Mac, so going back affects every project's agents; the dry run lists the other vaults and the next steps. `--no-wire` creates the vault and stops. It belongs to the resolved form alone: `kscope init --no-wire` and `kscope init --no-wire`. The forms that name a ROOT wire nothing, and no flag makes them: that is what makes them the forms a script, an installer or a test drives against a root of its own choosing. `--no-wire` is not accepted there either -- in that position it would be read as a durability and refused as one. The call command reads one JSON request from stdin. OPERATION is one of: AGENT search | remember OPERATOR memory_lifecycle | memory_import | maintenance | ontology | doctor Only the two agent verbs are published as MCP tools. A search is a read: it ranks, bounds and returns the served set and writes nothing to the vault, so repeating it is safe. `ledger: true` is accepted and `ledger: false` refused. Output. `call search` and `call remember` print a short text receipt. Add `--json` anywhere on the line for the full response object, which is what a script or a benchmark parses. Exit codes. 0 means applied: everything asked for happened. 2 means refused: nothing was applied and stdout carries a refusal envelope, so fix the request and re-send it whole. 3 means applied in part: the response says status partial and stdout carries results -- one entry per submitted item, in submission order -- so re-send only the items whose status is not a write. 141 means stdout was closed before kscope finished writing, as in `kscope licences | head`: nothing is printed about it, and whatever was already applied stays applied. `kscope mcp` exits 0 instead, because a closed stdout is its client leaving. What a model never sees. call search returns the bounded public result. How that result was scored, the signed decision payload and engine diagnostics are withheld on every public channel, on both doors. The model command reports the embedding model built into this executable, and a release must carry one. The gate command reports the alpha entitlement gate without reading a key or opening a vault. The licences command prints the notices for the third-party components this one-file binary redistributes; `licenses` is accepted as a spelling. The schema command prints one OPERATION's full descriptive parameters and closed values. MCP derives a versioned compact, omission-first inputSchema from the same operation semantics. The two preserve the same non-null machine constraints but are intentionally not byte-identical: the native decoder accepts legacy explicit null while MCP omits absent optionals. Pass no OPERATION to list them under prose headings, or `--list` for the same operations as a JSON object, which is what a caller enumerating them should read. The activate command reads KALEIDOSCOPE_API_KEY, then the key file, then a KEY given as the argument, then standard input, in that order -- so a stale environment variable wins over what was typed. `kscope activate ` is the form an agent can use: an agent runs one command at a time, so an export from a previous invocation is gone and a pipe needs a pipeline it did not build. `-h` and `-V` are accepted as short forms of `--help` and `--version`. Fuller prose than this page carries lives with the source; `kscope schema` is the machine-readable half and ships here.