How the Agent Thinks
Overview of Krnl's reasoning model, prompt construct, sandboxed tool adapter execution, and memory design.
High-Level Architecture
Each Krnl agent consists of a structured prompt pipeline, configured tool adapters, short-term/long-term memory stores, and a deterministic execution runtime. The runtime constructs prompt states, executes tools safely, and logs outputs.
Structured system prompt with Observe-Plan-Act-Reflect phases, context injection, and tool schemas
Sandboxed execution layer for file operations, shell commands, HTTP requests, and more
Short-term context for current session + long-term structured memory across sessions
Deterministic state machine with approval gates, rollback, and trace logging
Prompt Pipeline (Observe-Plan-Act-Reflect)
The agent reasons in four distinct phases, each with specific responsibilities:
Collects project context: active file statuses, recent commit trees, compiler logs, diagnostics, and user commands. Builds a mental model of the current state.
Generates a list of logical steps with explicit dependencies. Plans are validated by the runtime before starting execution. User approval required for destructive actions.
Executes plan steps using local sandboxed tool adapters (shell executor, file editor, HTTP clients). Each tool call is logged and can be rolled back.
Compiles final results, verifies test suites, drafts explanations, records memory entries, and generates trace logs for auditability.
Live Example
Watch the agent think through a task: “add rate limiting to the API endpoint”
Tool Model & Adapters
Tools are structured modules with explicit schemas defining inputs and outputs. The runtime validates all outputs and prevents the execution of arbitrary commands unless authorized in `AGENT.md`.
Available Tools
read_file, write_file, edit_file, list_dir, search_files — with path validation and backup
run_command — with timeout, output capture, and approval for destructive commands
web_fetch, web_search — with rate limiting and content extraction
memory_write, memory_query — structured fact storage and retrieval
Memory & Context
The memory system divides data into two layers for optimal performance and persistence:
- • Active file contents and diagnostics
- • Recent tool outputs and errors
- • Current plan state and progress
- • Conversation history (compacted)
- • Ephemeral — cleared after session
- • Project facts and conventions
- • Architecture decisions
- • Error and solution records
- • User preferences and constraints
- • Persistent — survives sessions
Safety Layers
Safety checks are executed at three key tiers to prevent unintended actions:
All tool inputs are validated against schemas. Path traversal attacks are blocked. Command injection is prevented.
Destructive operations require user approval. The agent shows proposed changes before executing. Rollback is always available.
Every action is logged with timestamp, context, and outcome. Trace logs enable debugging and compliance auditing.
Complete Example Trace
Here is a complete trace log representing a task from start to finish: