Crate Reference

Koyal is an 11-crate Cargo workspace plus the root CLI/library package. Strict dependency layering is validated by scripts/ci/check_workspace_contract.sh on every CI run.

Dependency Graph

koyal-api                                      (no heavy deps)
  ↑
  ├── koyal-config        (api)
  ├── koyal-memory        (api)
  ├── koyal-chains        (api)
  ├── koyal-dexes         (api + chains)
  ├── koyal-exchanges     (api)
  ├── koyal-providers     (api + config)
  ├── koyal-core          (api + memory)
  └── koyal-runtime       (api + config + memory + providers + core)
         ↑
         ├── koyal-gateway        (api + config + core + runtime + integrations)
         └── koyal-integrations   (api + config + runtime)
                ↑
                └── koyal            (CLI facade — depends on everything)

`koyal-api` — Public Traits

Zero heavy dependencies. Every other crate depends on this one. Defines all trait boundaries.

Trait / Type	File	Purpose
`AgentHarness`	`harness.rs`	Tick engine — `tick()`, `capabilities()`, `supports()`
`ModelProvider`	`provider.rs`	AI provider interface — `call()`, `health_check()`, `capabilities()`
`Memory`	`memory.rs`	Storage — `store()`, `recall()`, `forget()`, `prefetch()`, `sync_turn()`
`TradingExecutorHandler`	`executor.rs`	DEX executor — `execute()`, `validate()`, lifecycle
`Tool`	`tool.rs`	Agent tool interface — `execute()`, `schema()`, `is_read_only()`
`ApprovalDecision`	`approval.rs`	Permission result: `Allow`, `Deny(String)`, `Prompt{request_id}`
`ClassifiedError`	`error.rs`	Error taxonomy: 15 `FailoverReason` values with recovery hints
`ManagedAgent`	`agent_types.rs`	Agent + Bot + Loop + Executor + Wallet data types

`koyal-config` — Configuration

File	Purpose
`schema.rs`	`AppConfig` — env-driven with dotenvy, serde derive
`frontmatter.rs`	YAML frontmatter parser for legacy `agent.md` files

Environment variables: AI_GATEWAY, AI_MODEL, OPENAI_API_KEY, ANTHROPIC_API_KEY, SOLANA_RPC_URL, SOLANA_KEYPAIR_PATH, etc.

`koyal-memory` — Persistence

File	Purpose
`sqlite.rs`	`SqliteMemory` — rusqlite with FTS5 full-text search, WAL mode, agent isolation
`store.rs`	`AgentMemory` — high-level memory operations
`jsonl.rs`	Append-only JSONL for audit-compatible trade ledgers
`journal.rs`	Structured `journal.md` writer
`learnings_store.rs`	`learnings.md` with word-overlap deduplication
`positions.rs`	Derive positions from trade ledger
`vault.rs`	`MarkdownVault` — agent bible manager (soul, instructions, memories, bots)

`koyal-providers` — AI Providers

File	Purpose
`lib.rs`	`resolve_provider()` — priority-based provider selection
`openai.rs`	OpenAI Chat Completions
`anthropic.rs`	Anthropic Messages API
`catalog.rs`	55+ provider presets (OpenRouter, DeepSeek, Groq, Together, etc.)
`auth_store.rs`	AES-256-GCM encrypted credential vault
`model_router.rs`	Failover chain with circuit breaker
`health_monitor.rs`	Periodic provider health pings
`secret_mask.rs`	API key redaction for safe logging
`usage_store.rs`	Token/latency usage tracking

`koyal-core` — Stores and Types

In-memory stores for the runtime state:

Store	Purpose
`ManagedAgentStore`	Agent registry
`BotStore`	Bot registry, scoped by agent
`AgentLoopStore`	Loop definitions and state
`TradeStore`	Trade proposal queue
`OrderStore`	Executor order tracking
`WalletStore`	Wallet registry
`SettingsStore`	Runtime settings key-value
`LogStore`	Structured log buffer
`McpServerStore`	MCP server registry
`ConnectionStore`	Integration connections

`koyal-chains` — Chain Protocols

Module	Purpose
`solana/`	Solana RPC client, transaction signing, Ed25519 keys
`evm/`	alloy provider, SECP256k1 signing, multi-chain RPC
`wallet.rs`	BIP39 mnemonic generation, BIP32 derivation

`koyal-dexes` — DEX Integrations

Module	Purpose
`jupiter/`	Jupiter v6 swap API — quote, route, execute
`uniswap/`	Uniswap v3 SDK + v4 SDK wrappers

`koyal-exchanges` — Centralized / Perp Venues

Module	Purpose
`hyperliquid/`	hyperliquid-rust-sdk + hypersdk. Orders, positions, leverage.
`polymarket/`	polymarket-client-sdk. Market queries, CLOB orders.

`koyal-runtime` — Tick Engine

The core execution engine.

File	Purpose
`harness.rs`	`CoreHarness` — coordinates everything
`tick.rs`	Single agent tick: load bible → RAG recall → provider call → approval check → execute
`permission.rs`	`PermissionEngine` — bot policies, wallet roles, scoped authorize
`approval.rs`	Approval flow manager
`scheduler.rs`	Cron scheduler for loops
`skills/`	`SkillRegistry` — load, state, pin/unpin
`guardrails.rs`	Pre/post tick safety checks

`koyal-gateway` — HTTP API

Axum-based HTTP gateway.

File	Purpose
`lib.rs`	`AppState`, `create_router_with_state()`, `start_server()`
`routes.rs`	All 50+ route handlers
`static_files.rs`	Serves `web/dist/` — SPA fallback, asset caching
`mcp.rs`	MCP server — `harness_tools()`, `dispatch_mcp_call()`
`connectors.rs`	Integration connector catalog and defaults
`setup.rs`	Setup checklist logic

`koyal-integrations` — Loop Blueprints and Channels

Module	Purpose
`loops/blueprints.rs`	Built-in loop blueprints: `price_watcher`, `wallet_monitor`, etc.
`loops/runner.rs`	Loop execution runner
`telegram/`	Telegram bot, sender pairing, channel provisioning
`webhook/`	Outbound webhook integration
`metrics/`	Prometheus metrics export
`polymarket/`	Polymarket integration hooks

`koyal` — CLI

Root package. Thin facade over the workspace crates.

File	Purpose
`src/lib.rs`	`Commands` enum (clap derive), all subcommand enums
`src/main.rs`	`main()` — parse args, dispatch to crates
`src/gateway/mod.rs`	Re-exports from `koyal-gateway`

Keyboard shortcuts

Koyal Docs