@kaleidorg/mind) is a local-first, agentic reasoning and tool-calling engine for a multi-L2 Bitcoin wallet. It is a pure library, an Engine for the agentic loop, a ToolRegistry with pluggable ToolSources, a SkillRegistry, and an injected LLMProvider, that runs identically on a phone and a laptop.
The design starts from a hard constraint: small on-device models are slow and unreliable at multi-step planning. KaleidoMind avoids asking them to do that work.
KaleidoMind does not run by itself, it is a library embedded by a host: the Rate mobile wallet (React Native, fully on-device QVAC), the Desktop App’s Tauri sidecar, or an eval and benchmark harness. KaleidoAgent does not currently use this library, it has its own separate agent loop. See Relationship to KaleidoAgent below.
The Tiered Funnel
Most requests never reach the model at all.- T0, fast path. Deterministic pattern match, no inference. Balance checks, addresses, spot prices.
- T2, recipe engine. A skill carries the ordered plan (resolve, price, convert, confirm, send); the model only fills the slots. That makes multi-step flows reliable even on a ~0.6B parameter model, instead of asking the model to plan the whole chain itself.
- T1, full agentic loop. Everything else, scoped to the skill’s own tool list so a small model never has to reason over the entire tool surface at once. Discovery flows (for example merchant-finder) intentionally lean more on the model for natural-language understanding.
One Tool Contract, Many Transports
The host connects tool sources to the same engine. MCP discovers server schemas; in-process adapters bind the core contracts. Names and arguments can differ, so check the connected source rather than assuming transport compatibility:
The canonical tool contract lives in core as
ToolDef[], with a spend flag that maps to requiresConfirmation: true. For tools carrying this flag, the Engine pauses and calls the host’s onConfirm before executing. Custom tools must declare their risk, and MCP classification depends on the installed adapter version. The confirmation sheet gets a deterministic, voice-first readback (for example “Send 4,800 sats to bob over Spark. Confirm?”) built from the resolved call, not generated by the model, so a wrong unit or recipient surfaces where it can be caught.
Per-Layer Wallet Tools
rln_issue_asset is part of the KaleidoMind contract and runs against the mock wallet in @kaleidorg/mind/testing, but kaleido-mcp does not expose an issuance tool yet, so a host bound to the gateway cannot issue an RGB asset through it today.
Plus cross-cutting router tools: get_balances(layer?), resolve_contact(name), get_price(asset?, fiat?), fiat_to_sats(amount, currency), get_swap_quote/execute_swap, the unified send_payment(asset, amount, to, layer?) that picks the rail automatically, and its receive counterpart create_invoice(asset?, amount?, layer?).
KaleidoSwap Trading & LSPS1
Separate contracts for DEX trading (kaleidoswap_get_quote, then kaleidoswap_atomic_init/execute/status; kaleido-mcp 0.3.0 settles swaps atomically only) and LSP-agnostic channel orders (lsp_get_info, lsp_get_network_info, lsp_estimate_fees, lsp_create_order, lsp_get_order). The atomic swap chain runs as a single confirm-gated recipe (kaleidoswapAtomicRecipe): quote, then after one confirmation init on the maker, read the node’s pubkey, whitelist the HTLC as taker, and execute.
Skills
Skills are Agent-Skills-spec playbooks (SKILL.md plus progressive disclosure) that scope which tools are visible and, for the agentic tier, carry the playbook itself. Bundled skills include per-wallet playbooks (spark-wallet, rgb-lightning-node), trading and channels (kaleido-trading, kaleido-lsps, flashnet-swaps, channel-manager, liquidity-optimizer), portfolio automation (portfolio-manager, dca), spending and data (bitrefill, paid-data, wallet-assistant), and a more model-leveraging merchant-discovery skill (merchant-finder, location plus BTC Map via pluggable embedding selectors). Payment and receive flows ship as T2 recipes rather than skills.
QVAC: On-Device Inference
LLM, embedding, speech-to-text, and text-to-speech inference all run through the QVAC SDK, Tether’s local AI runtime, locally on the device. Offloading inference to another device is planned but not available yet. Published as the@kaleidorg/mind/qvac subpath so the SDK stays a peer dependency rather than a hard requirement of core. Memory and RAG (long-term recall, wallet-history retrieval, merchant discovery) also route through QVAC’s embeddings, with near-duplicate consolidation to keep memory from bloating.
Recommended models
KaleidoMind recommends the Qwen3.5 family. Every model below is a@qvac/sdk registry constant, so loadModel({ modelSrc: QWEN3_5_2B_MULTIMODAL_Q4_K_M }) downloads and caches it. Qwen3 and Hermes 3 are no longer recommended: the small Qwen3 models garbled the arguments of multi-field wallet calls such as rln_issue_asset.
The same list is exported as
QWEN35_MODELS from @kaleidorg/mind/qvac.
createQvacProvider turns the SDK’s completion into the engine’s LLMProvider. The SDK functions are injected rather than imported, so the host owns the model lifecycle (loadModel, unloadModel) and the engine never pulls QVAC into a bundle that does not need it.
Build With It
The@kaleidorg/mind README has a quickstart, and the kaleido-mind repository carries two runnable examples:
@kaleidorg/mind/testing provides a stateful MockWallet bound to the real tool contract and a scripted provider, so the full funnel, recipes and confirm gate run in CI or on a laptop with no node, no funds and no model.
For a step-by-step version on signet, follow Build a Local RGB Agent.
Where It Runs
The fastest way to try it is the Desktop App. Download the latest release and follow the installation guide.
Relationship to KaleidoAgent
KaleidoAgent is a separate, always-on Node.js server (Nanobot runtime, scheduling, Telegram) that predates KaleidoMind’sEngine and has not migrated its agent loop onto Mind. It already consumes the skill playbooks shipped in @kaleidorg/mind, while retaining its own runtime. The two are conceptually the same idea (an agentic loop over a tool registry with a confirm gate) implemented twice. Converging them, having KaleidoAgent host KaleidoMind’s Engine instead of its own loop, is a known, not-yet-started integration path; until then, treat them as independent systems that both consume kaleido-mcp.
Publishing & Subpaths
Published frompackages/core as @kaleidorg/mind, with subpaths: ./mcp (MCP tool source helpers), ./skills (skill loader), ./logger, ./qvac (on-device inference), ./openai (OpenAI-compatible model servers), ./kaleidoswap, ./lsps1, ./submarine, ./bitrefill, ./flashnet, ./knowledge, and ./testing (mock wallet and scripted provider). Also on npm: apps/provider as @kaleidorg/mind-provider, the Tauri desktop sidecar that the Desktop App embeds. The CLI in apps/cli is for terminal and eval use from the repository and is not published.