MCP reference

Kaleidoscope publishes two MCP tools. search reads memory, remember writes it. Nothing else is callable by a model.

kscope init registers the server with every editor it finds. Each one starts kscope mcp --profile with the project’s profile and talks to it over stdio at MCP protocol revision 2025-11-25.

Machine-readable tool reference · Install

search

Send exactly one of query or memory_id. Every other field applies to a ranked query and is refused alongside memory_id.

field	notes
query	Ranked selection. Hits come back under selected_hits.
memory_id	Addressed read of one mem_... record. No ranking, no filtering.
top_k	Memories served, in rank order. Five is a normal value.
candidate_pool	How many results each retrieval channel may propose before the final cut. Independent of top_k.
maximum_context_bytes	The byte budget the served set is bounded to.
ledger	Only true is accepted.
as_of	RFC 3339 instant validity is evaluated at. Omitted means now.
scope	project, branch, artifact. An omitted axis matches every memory.
channels	Restrict which retrieval channels contribute.

{"query": "how do we handle database migrations", "top_k": 5}

Omit a knob and you get its published default. A value above its ceiling is refused rather than clamped.

A search writes nothing to your vault. It ranks, bounds and returns, so repeating it is safe, and many agents can search one vault at once. ledger is still accepted as true so callers that send it keep working; false is refused, because a ranked search is always the bounded one.

remember

field	when	notes
mode	always	create, update, or delete.
content_md	create, update	The memory as you want to read it back. Must begin with # .
semantic_delta	create, update	The structure committed with it. Fields below.
memory_id	update, delete	Which memory.
expected_version_id	update, delete	The active version you are allowed to replace.
items	instead of the pair above	Up to 50 creates in one call, applied in order.

Inside semantic_delta:

key	notes
title	Required. Your words — nothing scrapes it out of content_md.
memory_type	Required. Reuse an accepted name; types are append-only.
facts	Required, at least one. Each is subject, predicate, object; predicates are snake_case.
entities	Every surface your facts name, each with n, kind and is. Declare all of them or none.
occurred_at	When the facts are about, as {t, grain}. Kaleidoscope parses no date out of prose.
scope	project, branch, artifact.
evidence, corrections, propose, temporal, context	Optional.

{
  "mode": "create",
  "content_md": "# Ana owns the billing service\n\nAna took it over after the payments team split.",
  "semantic_delta": {
    "memory_type": "decision",
    "title": "Ana owns the billing service",
    "entities": [
      {"n": "Ana", "kind": "person", "is": "backend engineer on my team"},
      {"n": "billing service", "kind": "service", "is": "the service that issues invoices"}
    ],
    "facts": [{"subject": "Ana", "predicate": "owns", "object": "billing service"}]
  }
}

Write the is gloss properly. It is what the engine matches on when it decides whether two mentions of a name are the same thing, so Ana | person | backend engineer on my team finds far more than Ana alone.

remember infers nothing. The entities, facts and dates it stores are the ones you state.

A refusal names the field and what to change it to. Fix it and resend.

Reading the full contract

The tool schema your host discovered is the authority for the values a build accepts. Print the same contract from the shell:

kscope schema remember
kscope schema

What a model never sees

Lifecycle and import, maintenance, ontology and diagnostics are operator commands. They are absent from the tool list an agent discovers, and search results carry no handle that would reach them.

Next

Discovering the two tools is not the same as using them well. Give your agent the skill.