Agent Architecture

How the agent thinks,
acts, and remembers.

Octogent is built around a deterministic autonomous loop. Every task is decomposed, executed via native tools, and self-corrected — without human intervention, cloud APIs, or external dependencies.

8Parallel Worker Slots
25Max Iterations / Task
10+Native Tools
∞Runtime Duration

The Autonomous Loop

Every task Octogent receives passes through the same five-phase loop. The loop is deterministic, observable, and self-healing. It runs until the task is complete or the iteration limit is reached.

01
Task Intake & Queuing
A task arrives via the CLI, WebSocket gateway, or cron scheduler. It is validated, assigned a UUID, and placed in the task queue. The pool manager picks it up and assigns it to the next free worker slot.
// Gateway endpoint
ws://127.0.0.1:18789

// CLI
octogent task "Build a REST API for user auth"
02
Skill Selection & Memory Load
Before planning, the agent selects the appropriate skill profile (Coder, Researcher, Writer, DevOps) based on task content. Relevant memory entries from past sessions are loaded from SQLite and injected into the system prompt.
// Skill profiles
{ "skill": "coder", "focus": ["typescript","python","bash"] }
{ "skill": "researcher", "focus": ["web_search","web_fetch","analysis"] }
03
Planning (Think Phase)
The LLM receives the task and produces a structured plan — a sequence of atomic steps, each with a nominated tool and expected output. This plan is not fixed; it adapts as the agent observes results.
// Internal plan format
{ "step": 1, "tool": "bash", "intent": "scaffold project structure" }
{ "step": 2, "tool": "write_file", "intent": "generate route handlers" }
04
Tool Execution (Act Phase)
Each planned step is executed via the tool layer. Tools are sandboxed — bash commands run with timeout guards, file writes are scoped to the workspace, web fetches are rate-limited. Tool outputs are captured verbatim.
// Tool call format
{ "tool": "bash", "input": { "command": "npm init -y" } }
{ "tool": "write_file", "input": { "path": "src/index.ts", "content": "..." } }
05
Observation & Self-Correction
After each tool call, the model evaluates the output. If a step fails, it rewrites the approach and retries — up to maxIterations. On final success or failure, the task result is written to memory and the worker slot is freed.
// Retry policy
{ "maxIterations": 25, "retryOnToolFailure": true, "backoffMs": 500 }

System Architecture

CLI · WebSocket · Cron | v +---------------------------+ | Gateway | | ws://127.0.0.1:18789 | +------------+--------------+ | v +---------------------------+ | Worker Pool | | 8 × worker_threads | +--+--------+--------+------+ | | | v v v [W:1] [W:2] [W:3] ··· [W:8] | | | +--------+--------+ | v +---------------------------+ | Agent Loop | | Think → Act → Observe | +--+--------+--------+------+ | | | v v v [Ollama] [Groq] [Tools] [local] [cloud] [10+ ops] | | v v [SQLite Memory] [Workspace]

Built-in Tools

All tools are sandboxed and timeout-protected. The agent selects tools autonomously based on task requirements.

bashExecute shell commands with configurable timeout and working-directory scoping. Stderr and stdout captured separately.
read_fileRead files with optional line-range selection. Supports large files via chunked reading.
write_fileWrite or overwrite files. Parent directories created automatically.
list_dirList directory contents with file size, type, and modification timestamp metadata.
web_searchSearch the web via SearXNG (self-hosted or public). Returns ranked results with titles, URLs, and snippets.
web_fetchFetch and parse web pages. Returns cleaned text content, stripped of navigation and ads.
memory_saveSave key-value pairs to SQLite long-term memory with optional tags and TTL.
memory_readQuery long-term memory by key, tag, or semantic similarity (when embeddings enabled).
spawn_agentSpawn a sub-agent in a new worker slot to handle a parallel subtask. Returns task ID.
check_taskPoll the status and partial output of a spawned sub-agent task.

Skill Profiles

Skills shape how the agent approaches a task. Each skill is a JSON definition that sets the system prompt, preferred tools, and output style. Custom skills can be added to the skills/ directory.

Built-in
Coder
Optimized for software engineering tasks. Prefers bash, read_file, write_file. Uses structured code output with explanations. Ideal for API development, scripts, and automation.
Built-in
Researcher
Deep web research and synthesis. Uses web_search, web_fetch, memory_save heavily. Produces structured summaries with source citations.
Built-in
Writer
Long-form content generation. Drafts, outlines, and edits documents. Uses memory for consistency across multi-section outputs.
Built-in
DevOps
Infrastructure and deployment automation. Optimized for bash-heavy workflows, Dockerfile generation, CI/CD config, and system diagnostics.

Memory System

Octogent uses a SQLite-backed memory store that persists across all sessions. The agent reads from memory before each task and writes key findings on completion.

Storage Engine
SQLite (local file, ~/.octogent/memory.db). No cloud sync. No external service required. Fully private.
Write Trigger
Agent autonomously decides what to save using the memory_save tool. Key findings, learned patterns, and project context are persisted.
Read Strategy
On task start, the agent queries memory for relevant context using keyword and tag matching. Future versions will support vector similarity search.
TTL / Expiry
Optional per-entry TTL. Entries without TTL persist indefinitely. Manual pruning via octogent memory clear command.
Cross-Task Context
Sub-agents spawned via spawn_agent inherit a scoped read-only view of the parent task's memory context.

Parallel Execution

The worker pool manages eight independent execution slots. Each slot runs its own Node.js worker_thread — fully isolated memory, separate LLM context, independent tool state.

Isolation
Thread-level Isolation
Each worker runs in its own Node.js worker_thread. Memory spaces are isolated. A crash in one slot does not affect others.
Scheduling
FIFO Queue with Preemption
Tasks are queued FIFO. High-priority tasks (via octogent task --priority flag) can preempt lower-priority waiting tasks.
Spawning
Sub-Agent Spawning
Any running agent can spawn up to 4 sub-agents in new slots via the spawn_agent tool. Sub-tasks run fully concurrently.