Give your agent the skill

An agent uses memory only if something told it to. kscope init installs that something: one skill file, and a short marked block in whichever instruction file your project already has.

Install it

npm install -g @kleos-research/kaleidoscope
cd ~/your-project
kscope init

You should see the agents it wired, then a line per step:

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 claude-code
kscope:   claude for claude-code
kscope:   skill for claude-code

Kaleidoscope needs a key before any of this runs. Getting started says how to ask for one.

kscope init --no-wire creates the vault and leaves every file of yours alone.

Where each file lands

agent	instruction file	skill
Claude Code	a marked block in CLAUDE.md	.claude/skills/use-kaleidoscope/SKILL.md
Codex	a marked block in AGENTS.md	.agents/skills/use-kaleidoscope/SKILL.md
OpenCode	a marked block in AGENTS.md	.agents/skills/use-kaleidoscope/SKILL.md
Cursor	.cursor/rules/kaleidoscope.mdc, the whole file	none: Cursor has no skill directory
none detected	a marked block in AGENTS.md	none

Every path is inside the project. That is what carries them into the worktree or temporary clone an agent runs your work in.

kscope init looks for ~/.claude or ~/.claude.json, ~/.codex, ~/.cursor and ~/.config/opencode, and takes each one it finds as evidence you run that agent.

The files

SKILL.md

The skill: about 1,500 words telling an agent when to retrieve, what is worth persisting, and what never to store. One file, installed at a different path per agent.

ViewDownload

AGENTS.md snippet

The marked block for AGENTS.md, which Codex and OpenCode read. It points at the skill and states the rules in short, so an agent that never opens the skill still has them.

ViewDownload

CLAUDE.md snippet

The same block for CLAUDE.md, naming the skill path Claude Code reads.

ViewDownload

Cursor rule

The same block as a Cursor project rule, with alwaysApply: true. It names no skill file and points at kscope schema remember for the write contract instead.

ViewDownload

SKILL.md is byte for byte the file kscope init writes. The three snippets are the block it appends, without the one-line revision comment it stamps under the opening marker. /site-manifest.json records the sha256 of the source each was taken from, under public_upstream_sha256: download a file, take its sha256, compare.

What lands in your CLAUDE.md

This is the whole block. The two comments mark where Kaleidoscope’s text starts and stops.

CLAUDE.md

<!-- >>> kaleidoscope-manager owner=kaleidoscope-manager-v1 instruction=claude -->
## Kaleidoscope memory

This project's memory across sessions: decisions made, preferences stated, constraints, corrections, and what past work produced. `search` reads it, `remember` writes it. Memories, queries and results stay on this machine; the one network request is a licence check that sends Kleos's licence server the key, the platform and the kscope version, nothing from the vault.

**Prefer the CLI when you have a shell.** One invocation costs a couple of dozen tokens; the MCP tool definitions sit in your context all session (~1,800) whether or not you call them. Use the MCP `search`/`remember` tools only when you have no shell -- same engine, same vault.

```bash
echo '{"query":"how we handle retries","top_k":5}' | kscope call --profile default search
kscope schema remember   # the write contract, when you need it
```

**Search before you go looking.** Before grepping, reading your way around the code, or asking the user how this project works -- search first. Code shows what *is*; memory shows what was *decided*, and why. A question already settled here must not be asked twice.

**Write without being asked** when the user states a preference, makes or rejects a decision, sets a constraint, corrects you, or work produces a result worth keeping. Don't wait for "remember this", and don't batch writes to the end of the task -- write when it lands, while you still know why.

**Write what you had to dig for.** Those triggers are things the *user* did; this one is you. Whatever you established by reading code, running an experiment, or ruling out a wrong answer is the most expensive thing in a session to rediscover. **That applies hardest to agents you spawn.** A subagent or workflow agent sees only the prompt you write it, so put "search Kaleidoscope first, record what you establish" in that prompt -- or write its findings yourself when it reports back.

Never store secrets, transcripts, ordinary file contents, anything the code or git history already records, or ideas still in flux.

A refusal names the field to fix and what to change it to: correct it and resend. One refusal is never a reason to stop using memory.

Full write contract: `.claude/skills/use-kaleidoscope/SKILL.md`, or `kscope schema remember`.
<!-- <<< kaleidoscope-manager owner=kaleidoscope-manager-v1 instruction=claude -->

Nothing else in the file is touched, and a second run adds nothing.

Doing it by hand

If you ran kscope init --no-wire, or you use an agent this build has not heard of, pasting these files works.

1. Save SKILL.md to .claude/skills/use-kaleidoscope/SKILL.md for Claude Code, or .agents/skills/use-kaleidoscope/SKILL.md for Codex and OpenCode.
2. Paste the matching snippet into AGENTS.md, CLAUDE.md, or .cursor/rules/kaleidoscope.mdc. Keep both marker comments — they are what lets Kaleidoscope recognise the block as its own later and remove it exactly.

SKILL.md carries no marker, because its frontmatter is name and description and a strict reader can reject anything else. Ownership is recorded in a receipt written beside it, SKILL.md.kaleidoscope-instruction-owner.json.

Taking it back out

The shipped command has no removal verb. Delete the marked block including both of its comments, or the skill file and the receipt beside it.

kaleidoscope instructions install and instructions remove do this one file at a time. They belong to a second executable published on no channel, so the lines below are not commands you can run today.

kaleidoscope instructions install skill --host claude-code --project "$PWD"
kaleidoscope instructions remove cursor --project "$PWD"

Full command reference: agent instructions. What the two tools do: MCP reference. The same text as a single file: agent-instructions.md.