What Is This?

Strada.Brain is an AI agent you talk to through a chat channel. You describe what you want -- "create a new ECS system for player movement" or "find all components that use health" -- and the agent reads your C# project, writes the code, runs dotnet build, fixes errors automatically, and sends you the result.

It has persistent memory backed by SQLite + HNSW vectors, learns from past errors using hybrid weighted confidence scoring, decomposes complex goals into parallel DAG execution, automatically synthesizes multi-tool chains with saga rollback, and can run as a 24/7 daemon with proactive triggers. It supports multi-agent orchestration with per-channel session isolation, hierarchical task delegation across agent tiers, automatic memory consolidation, a runtime self-improvement loop that materializes reusable skill / workflow / knowledge_patch artifacts in shadow mode before promoting them to active guidance, a deployment subsystem with human-in-the-loop approval gates and circuit breaker protection, and a modern glassmorphism web portal with Magic UI components (shadcn/ui + 21st.dev) featuring animated metrics, blur transitions, and a persistent notification center.

New in this release: Strada.Brain now features an Agent Core -- an autonomous OODA reasoning engine that observes the environment (file changes, git state, build results), reasons about priorities using learned patterns, and takes action proactively. The multi-provider routing system dynamically selects the best AI provider for each task type (planning, code generation, debugging, review) with configurable presets (budget/balanced/performance). A confidence-based consensus system automatically consults a second provider when the agent's confidence is low, preventing errors on critical operations. All features gracefully degrade -- with a single provider, the system works identically to before with zero overhead.

This is not a library or an API. It is a standalone application you run. It connects to your chat platform, reads your Unity project on disk, and operates autonomously within the boundaries you configure.

Quick Start

Prerequisites

Node.js 20.19+ (or 22.12+) — if Node.js is not installed, the launcher will offer to download a portable copy automatically (Windows only, ~30 MB one-time download, stored in %LOCALAPPDATA%\Strada\node). You can also point to a custom binary with STRADA_NODE_PATH.
At least one supported AI provider configured (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, etc.), a Claude subscription token (ANTHROPIC_AUTH_MODE=claude-subscription + ANTHROPIC_AUTH_TOKEN), an OpenAI ChatGPT/Codex subscription session (OPENAI_AUTH_MODE=chatgpt-subscription), or an ollama-only PROVIDER_CHAIN
A Unity project (the path you give the agent). Strada.Core is recommended for full framework-aware assistance; without it, Strada.Brain still runs with reduced Strada-specific guidance.

1. Install

# Clone from source (currently the canonical install path)
git clone https://github.com/okandemirel/Strada.Brain.git Strada.Brain

# No `cd` required: use the checkout directly from the parent folder
./Strada.Brain/strada install-command
./Strada.Brain/strada setup

# Optional shorter shell
cd Strada.Brain

# Windows PowerShell source checkout
git clone https://github.com/okandemirel/Strada.Brain.git Strada.Brain
.\Strada.Brain\strada.ps1 install-command
.\Strada.Brain\strada.ps1 setup

Windows note: If PowerShell blocks .\strada.ps1 with an execution policy error, use strada.cmd instead (works in both CMD and PowerShell without policy changes):
.\Strada.Brain\strada.cmd install-command
.\Strada.Brain\strada.cmd setup
Or allow local scripts: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

If you see SyntaxError: Unexpected identifier 'pipefail', you ran node strada which tries to parse the bash launcher as JavaScript. Use .\strada.cmd, .\strada.ps1, or node strada.js instead.

./strada is the canonical source-checkout launcher on macOS/Linux. On Windows, use .\strada.ps1 from the checkout root, with strada.cmd as the companion wrapper for Command Prompt and bare-PATH launches. On first run the source launcher prepares the local checkout automatically, so normal setup no longer requires manual npm install, npm run bootstrap, or npm link.

No Node.js? No problem. On Windows, if node is not found on the system PATH, the launcher (strada.cmd / strada.ps1) will prompt you to download a portable Node.js automatically. The portable runtime is stored in %LOCALAPPDATA%\Strada\node and is used only by Strada — it does not modify your system PATH or interfere with other tools. You can skip the prompt and install Node.js yourself from https://nodejs.org, or point to any existing binary with set STRADA_NODE_PATH=C:\path\to\node.exe.

If you skip ./strada install-command, keep using ./Strada.Brain/strada ... from the parent folder or ./strada ... from the repository root. Once installed, bare strada ... works from anywhere.

On macOS/Linux, ./strada install-command updates your shell profile automatically so future terminals pick up the strada command without a manual PATH edit. On Windows, .\strada.ps1 install-command installs strada.cmd and strada.ps1 into %LOCALAPPDATA%\Strada\bin and updates the user PATH.

To remove the user-local command later, run strada uninstall (or ./strada uninstall / .\strada.ps1 uninstall from the checkout). Add --purge-config to also remove Strada runtime state such as .env, .strada-memory, .whatsapp-session, logs, and HEARTBEAT.md under the active runtime root. On source checkouts, the same --purge-config flag also removes generated artifacts like node_modules/, dist/, web-portal/node_modules, and web-portal/dist so you can rerun the checkout from a true zero-install state. The repository checkout itself is never deleted automatically.

If you ever run npm manually, do it from the repository root, the folder that contains package.json. If you see an error like ENOENT ... /Strada/package.json, you are one directory too high; either cd Strada.Brain first or prefix the command with cd Strada.Brain && ....

strada-brain is not currently published on the public npm registry, so npm install -g strada-brain will return E404. Until a registry release exists, use the source checkout flow above.

When Strada is installed from a packaged npm/tarball release, it keeps its runtime config in ~/.strada by default on macOS/Linux and %LOCALAPPDATA%\Strada on Windows instead of depending on the current working directory. Override this with STRADA_HOME=/custom/path when you need a different app home.

2. Setup

# Interactive setup wizard (terminal or web browser)
./strada setup

# Skip the chooser and jump straight into one setup surface
./strada setup --web
./strada setup --terminal

# Windows PowerShell source checkout
.\strada.ps1 setup
.\strada.ps1 setup --web
.\strada.ps1 setup --terminal

If ./strada setup --web detects an older Node runtime that cannot build the full portal bundle, Strada keeps web as the primary path. On macOS/Linux it prefers nvm and can relaunch setup for you after the upgrade, running that guided flow inside a temporary clean HOME so incompatible prefix / globalconfig npm settings do not block nvm. On Windows it prefers nvm-windows, then winget, then the direct Node download path, and it always shows the exact rerun command for .\strada.ps1 setup --web. If you decline the upgrade, Strada offers to continue with terminal setup instead. If Node 22 is already installed in nvm, Strada reuses that runtime instead of downloading it again. The setup browser flow opens on the root local URL and stays on that same URL when it hands off to the main app. That first-run browser open also carries an explicit setup flag, so a stale cached portal tab still resolves into the setup wizard instead of a dead "Not Found" page. If the first web handoff races the restart, Strada now retries that launch automatically before surfacing an error. Once the config is saved, Strada keeps the handoff page alive on the same URL until the main app is ready, so do not re-run setup.

The wizard asks for your Unity project path, AI provider access, default channel, language, and per-provider default model selections. ./strada setup now prefers Web Browser by default; choose Terminal only when you explicitly want the faster text flow. The configured UNITY_PROJECT_PATH is the authoritative project scope for Strada's coding work. If another Unity project is currently open in the editor, Strada may surface a startup warning about the mismatch, but it does not silently switch scope away from the setup-selected project. Terminal setup accepts comma-separated providers in a single prompt (e.g. kimi,deepseek) for fallback / multi-agent orchestration, or you can add them one at a time interactively. The "Add another?" loop only appears when a single provider is entered. The embedding provider choice stays separate. Every selected response worker must pass preflight before setup can finish. Setup, strada doctor, and startup now use the same contract, so invalid provider chains are rejected instead of being silently skipped. Fresh setup now enables both multi-agent orchestration and task delegation by default. If you want the legacy single-agent path, explicitly set MULTI_AGENT_ENABLED=false; delegation does not initialize when multi-agent is disabled even if TASK_DELEGATION_ENABLED=true. When OpenAI uses chatgpt-subscription, setup validates the local Codex/ChatGPT session with a real Responses probe before saving. Expired subscription sessions are rejected during setup and reported by strada doctor. When Claude uses claude-subscription, setup expects an ANTHROPIC_AUTH_TOKEN generated after claude auth login --claudeai and claude setup-token, warns that Anthropic documents this flow as limited to Claude Code / Claude.ai, and still requires the selected response worker to pass preflight before save completes. After you save the web wizard, Strada exposes explicit handoff states on the same URL (saved, booting, ready, failed) so refreshes can survive the transition and bootstrap failures stay visible until you retry setup. That handoff is now server-owned: once the first resolved web identity/session exists, Strada sends one assistant-authored welcome in the configured language and applies any setup-time autonomy bootstrap exactly once. Setup writes global provider-model defaults into .env, while chat and Settings keep using identity-scoped provider/model overrides on top of those defaults. If the first real chat message is technical, Strada still starts solving immediately and only learns whatever name/style/detail preferences it can infer from that same reply. If RAG is enabled without a usable embedding provider, the wizard now lets you continue to the review step but keeps Save blocked until you choose a valid embedding provider or disable RAG.

Windows web setup fix: Earlier versions had a path-separator bug that caused the web setup page to appear blank on Windows (all static assets were blocked by the path traversal guard). This is now fixed — both .\strada.ps1 setup --web and the post-setup web portal at 127.0.0.1:3000 work correctly on Windows. If you previously had to fall back to terminal setup on Windows, web setup is now the recommended path.

After the first successful setup, running ./strada with no subcommand becomes your smart launcher:

first use: opens setup automatically if config is missing
later uses: shows a terminal launcher so you can choose web, CLI, daemon mode, setup, or doctor

After setup, run a readiness check before you start the agent:

# From the source checkout
./strada doctor

# Or, after installing the user-local command
strada doctor

# Windows PowerShell source checkout
.\strada.ps1 doctor

For git/source installs, strada doctor treats a missing dist/ folder as a warning when the source launcher is already usable. It now shows the exact repo-root npm run bootstrap command only when you want packaged build artifacts.

Alternatively, create .env manually:

# Claude via API key
ANTHROPIC_API_KEY=sk-ant-...

# Or Claude via subscription token
# 1. claude auth login --claudeai
# 2. claude setup-token
ANTHROPIC_AUTH_MODE=claude-subscription
ANTHROPIC_AUTH_TOKEN=sk-ant-sid01-...

# Or use another supported provider key instead
UNITY_PROJECT_PATH=/path/to/your/UnityProject  # Must contain Assets/
# Optional: enable internal system auth / JWT sessions
JWT_SECRET=<generate with: openssl rand -hex 64>

3. Run

# Smart launcher from the source checkout
./strada

# Windows PowerShell source launcher
.\strada.ps1

# Bare command after `./strada install-command`
strada

# Start your configured default channel directly in daemon mode
./strada --daemon

# Start with default web channel
./strada start

# Interactive CLI mode (fastest way to test)
./strada start --channel cli

# Daemon mode (24/7 autonomous operation with proactive triggers)
./strada start --channel web --daemon

# Other chat channels
./strada start --channel telegram
./strada start --channel discord
./strada start --channel slack
./strada start --channel whatsapp

# Always-on supervisor with auto-restart
./strada supervise --channel web

4. CLI Commands

./strada                  # Canonical source-checkout launcher
.\strada.ps1             # Canonical Windows PowerShell source-checkout launcher
strada.cmd               # Windows Command Prompt companion launcher inside the checkout
node strada.js            # Universal Node.js entry point (works on any OS without shell wrappers)
./strada install-command  # Install a user-local bare `strada` command
.\strada.ps1 install-command # Windows source-checkout bare-command install
./strada uninstall        # Remove the installed bare command and managed PATH/profile changes
.\strada.ps1 uninstall    # Windows source-checkout bare-command uninstall
strada uninstall --purge-config # Also remove Strada runtime state and source-checkout generated artifacts for a zero-install rerun
strada                    # Smart launcher after install-command
strada --daemon           # Start the configured default channel in daemon mode
strada --web              # Open the web channel, or continue web-first setup on a fresh machine
strada --terminal         # Open the terminal channel, or force terminal setup on a fresh machine
./strada setup --web      # Launch the browser wizard directly
./strada setup --terminal # Use the terminal wizard directly
.\strada.ps1 setup --web  # Windows PowerShell browser wizard
.\strada.ps1 setup --terminal # Windows PowerShell terminal wizard
./strada doctor           # Verify install/build/config readiness
.\strada.ps1 doctor       # Windows PowerShell readiness check
./strada start            # Start the agent
./strada supervise        # Run with auto-restart supervisor
./strada update           # Check and apply updates
./strada update --check   # Check for updates without applying
./strada version-info     # Show version, install method, update status

4. Talk to It

Once running, send a message through your configured channel:

> Analyze the project structure
> Create a new module called "Combat" with a DamageSystem and HealthComponent
> Find all systems that query for PositionComponent
> Run the build and fix any errors

Web channel: No terminal needed -- interact through the web dashboard at 127.0.0.1:3000.

5. Auto-Update

Strada.Brain automatically checks for updates daily and applies them when idle. Source checkouts and ./strada install-command installs update through git — including automatic npm install for new dependencies and a post-update health check that rolls back on failure. After a successful git auto-update, Strada also refreshes the installed bare-command wrappers so strada keeps following the current checkout. npm-based update commands only apply after a public npm release exists. Auto-restart only triggers when running under strada daemon; direct strada start users receive a notification to restart manually. Immediate update checks can be triggered via POST /api/update (requires dashboard auth).

Variable	Default	Description
`AUTO_UPDATE_ENABLED`	`true`	Enable/disable auto-update
`AUTO_UPDATE_INTERVAL_HOURS`	`24`	Check frequency (hours)
`AUTO_UPDATE_IDLE_TIMEOUT_MIN`	`5`	Minutes idle before applying update
`AUTO_UPDATE_CHANNEL`	`latest`	npm dist-tag: `stable` or `latest`
`AUTO_UPDATE_NOTIFY`	`true`	Send update notifications when checks or installs occur
`AUTO_UPDATE_AUTO_RESTART`	`true`	Auto-restart after update when idle (requires `strada daemon`)

Web Portal

The built-in web portal (http://localhost:3000) provides a full AI workspace with 4 context-adaptive modes:

Mode	Shortcut	Description
Chat	`Alt+1`	Conversational interface with file attachments, voice input, and markdown rendering
Monitor	`Alt+2`	Real-time DAG visualization of goal decomposition, task statuses, review pipeline, and intervention controls
Canvas	`Alt+3`	Visual workspace with tldraw — 9 custom shapes (CodeBlock, UMLClass, APIEndpoint, DataFlow, etc.) auto-generated from agent output
Code	`Alt+4`	IDE-like view with Monaco editor (multi-tab, syntax highlighting), file tree explorer, and terminal output

Auto-switching: The portal automatically switches modes based on agent activity — goal execution opens Monitor, file writes open Code, visual output opens Canvas. Users can override with manual mode selection; sending a chat message resets the override.

Keyboard shortcuts: Alt+1-4 mode switching, Cmd/Ctrl+B toggle sidebar, Cmd/Ctrl+\ toggle secondary panel, Cmd/Ctrl+? shortcuts help.

Stack: React 19, Vite, Tailwind CSS v4, shadcn/ui, Zustand, TanStack Query, Radix UI, ReactFlow, tldraw, Monaco Editor.

Modern UI with Shadcn/UI + 21st.dev

The web portal features a premium glassmorphism design powered by shadcn/ui and community components from 21st.dev and Magic UI:

Glassmorphism theme: backdrop-blur, translucent surfaces, glow effects, and micro-interactions across all panels
Magic UI components: NumberTicker (animated metrics), BlurFade (page transitions), BorderBeam (active cards), TypingAnimation ("Thinking..." indicator), SparklesText (brand sparkles), ShimmerButton (send shimmer), CoolMode (confetti easter egg)
Sonner notifications: Toast system with auto-dismiss, severity colors, undo actions + persistent Notification Center sheet
Collapsible admin nav: 11 admin pages accessible from sidebar with route-aware auto-expand
Shared primitives: PageSkeleton, PageError, CopyButton, Sparkline, StatusDot, Badge, Sheet, ScrollArea, Input, Table

Skill Ecosystem

Skills are optional capability bundles you can install, share, and build on top of Strada.Brain. Each skill is a directory with a SKILL.md manifest and optional environment configuration.

Installing skills

# Install from any public git repository
strada skill install https://github.com/okandemirel/strada-skill-example

# List installed skills and their status
strada skill list

# Update all managed skills
strada skill update

# Search the public registry
strada skill search <query>

# Show details for an installed skill
strada skill info <name>

# Enable or disable a skill
strada skill enable <name>
strada skill disable <name>

# Remove a skill
strada skill remove <name>

Creating a skill

A skill is a directory containing at minimum a SKILL.md file with YAML frontmatter:

---
name: my-skill
version: 1.0.0
description: A short description of what this skill does
author: your-name
requires:
  bins:
    - some-cli-tool        # must exist in PATH
  env:
    - MY_API_KEY           # must be set
  skills:
    - another-skill        # dependency on another skill
capabilities:
  - code-generation
  - analysis
---

The body of SKILL.md is the system prompt or documentation injected into
the agent when this skill is active.

3-tier loading

Skills are discovered from three locations, in priority order:

Tier	Location	Purpose
workspace	`.strada/skills/` in your project root	Project-specific skills, highest priority
managed	`~/.strada/skills/`	User-installed skills via `strada skill install`
bundled	`src/skills/bundled/` inside the Strada.Brain checkout	Shipped with the application, always available

Skills in a higher-priority tier override those with the same name in lower tiers. A skill whose requires conditions are not met is placed in gated status and excluded from the active tool surface until its prerequisites are satisfied.

Registry

The public skill registry is a JSON index of community-maintained skills (11 skills and growing). Run strada skill search to browse it. Each entry lists the git repository, description, tags, version, and author. The registry URL is configurable via SKILL_REGISTRY_URL.

Bundled Skills

These skills ship with Strada.Brain and are always available:

Skill	Description	Requirements
`hello-world`	Test skill that echoes messages	None
`github-utils`	PR status, issue list, repo info via `gh` CLI	`gh` binary
`unity-helpers`	Find scripts, list scenes, check project structure	None
`web-search`	Fetch URLs, search via DuckDuckGo	None
`file-utils`	Word count, line count, find duplicates, directory size	None
`system-info`	OS uptime, CPU/memory/disk resources, network interfaces	None
`json-utils`	Format, query (dot-path), diff/compare JSON objects	None

Community Skills

Install from the registry with a single command:

strada skill install notion

Skill	Description	Requirements
`notion`	Search pages, read content, create pages	`NOTION_API_KEY`
`google-calendar`	List events, create events, today's schedule	`GOOGLE_CALENDAR_API_KEY`
`spotify`	Now playing, search tracks, playback control	`SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
`home-assistant`	Entity states, toggle devices, call services	`HA_URL`, `HA_TOKEN`

Web Portal Marketplace

The web portal includes a Marketplace tab at /admin/skills where you can browse, search, and install skills from the community registry with one click. Installed skills appear in the Installed tab with enable/disable controls.

Codebase Memory Vault

Persistent, per-project codebase memory that replaces per-request file re-reading with hybrid (BM25 + vector) and symbolic (Personalized PageRank over a call/import graph) retrieval. The vault lets Strada.Brain "know" a Unity project — or its own source — without streaming files into every turn. Massive token savings on large projects.

The vault is opt-in: set STRADA_VAULT_ENABLED=true. Once enabled, it boots alongside the agent, indexes Strada.Brain's own source via SelfVault, and exposes tools, HTTP APIs, and a portal page.

# Enable
export STRADA_VAULT_ENABLED=true
npm start

# In any channel
/vault init /path/to/unity/project
/vault sync
/vault status

Two phases shipped:

Phase 1 — Hybrid retrieval: SQLite per-vault at <project>/.strada/vault/index.db (better-sqlite3, WAL + foreign_keys). FTS5 BM25 + HNSW vectors fused via Reciprocal Rank Fusion (k=60). Token-budget-aware greedy packing. Three update paths: chokidar watcher (800ms debounce), write-hook (200ms budget), manual /vault sync. xxhash64 short-circuit skips unchanged files.
Phase 2 — Symbol graph + PPR: Tree-sitter WASM extractors for TypeScript, C#, and Markdown wikilinks. New tables vault_symbols, vault_edges, vault_wikilinks. Symbol IDs in <lang>::<relPath>::<qualifiedName> form. Personalized PageRank re-ranks results when focusFiles is set. graph.canvas (JSON Canvas 1.0) regenerated atomically on cold start, /vault sync, and watcher drain. SelfVault indexes Strada.Brain's own source (src/, web-portal/src/, tests/, docs/, AGENTS.md, CLAUDE.md); symlinks are skipped for security.

Tools registered with the agent: vault_init, vault_sync, vault_status.

HTTP surface at /api/vaults/*:

Method	Path	Purpose
GET	`/api/vaults/:id/canvas`	Serve `graph.canvas`
GET	`/api/vaults/:id/symbols/by-name?q=X`	Find symbols by short name
GET	`/api/vaults/:id/symbols/:symbolId/callers`	List incoming call edges
POST	`/api/vaults/:id/search`	Hybrid search (request body capped)

WebSocket vault:update broadcasts dirty-set batches.

Portal: /admin/vaults — Files (tree + markdown/raw preview), Search (hybrid query), Graph (renders graph.canvas via @xyflow/react + @dagrejs/dagre).

Configuration: config.vault.enabled (env STRADA_VAULT_ENABLED), config.vault.writeHookBudgetMs (default 200ms), config.vault.debounceMs (default 800ms), config.vault.embeddingFallback ('none' | 'local'), config.vault.self.enabled (set to false to opt out of SelfVault).

See docs/vault.md for the full reference (architecture, query pipeline, HTTP API shapes, security posture, Phase 3 roadmap).

Architecture

Agent Core v2 (in progress, behind default-off flags): the reactive Orchestrator (PAOR Agent Loop) shown below is being migrated onto a unified control plane in src/agent-core/control/ — one RunClock / Budget / FailureLedger / typed CancelReason, replacing v1's scattered 5 timeouts + 3 failure counters — reached through an AgentRunner seam (src/agent-core/runner/). It is a strangler-fig rewrite that preserves v1's incident-hardening; every flag defaults off, so current behavior is byte-identical to v1. See src/agent-core/README.md and plans/agent-core-v2/.

+-----------------------------------------------------------------+
|  Chat Channels + Web Portal (4-mode workspace, shadcn/ui + Magic UI) |
|  Web | Telegram | Discord | Slack | WhatsApp | CLI | Matrix     |
|  IRC | Teams                                                     |
+------------------------------+----------------------------------+
                               |
                    IChannelAdapter interface
                               |
+------------------------------v----------------------------------+
|  Orchestrator (PAOR Agent Loop)                                  |
|  Plan -> Act -> Observe -> Reflect state machine                 |
|  Instinct retrieval, failure classification, auto-replan         |
+-------+--------------+-------------+-----------+----------------+
        |              |             |           |
+-------v------+ +-----v------+ +---v--------+ +v-----------------+
| AI Providers | | 30+ Tools  | | Context    | | Learning System  |
| Claude (prim)| | File I/O   | | AgentDB    | | TypedEventBus    |
| OpenAI, Kimi | | Git ops    | | (SQLite +  | | Hybrid weighted  |
| DeepSeek,Qwen| | Shell exec | |  HNSW)     | | Instinct life-   |
| MiniMax, Groq| | .NET build | | RAG vectors| |  cycle           |
| Ollama +more | | Strada gen | | Identity   | | Tool chains      |
+--------------+ +------+-----+ +---+--------+ +--+---------------+
                        |           |              |
                +-------v-----------v--------------v------+
                |  Goal Decomposer + Goal Executor        |
                |  DAG-based decomposition, wave-based    |
                |  parallel execution, failure budgets    |
                +---------+------------------+------------+
                          |                  |
          +---------------v------+  +--------v--------------------+
          | Multi-Agent Manager  |  | Task Delegation             |
          | Per-channel sessions |  | TierRouter (4-tier)         |
          | AgentBudgetTracker   |  | DelegationTool + Manager    |
          | AgentRegistry        |  | Max depth 2, budget-aware   |
          +---------------+------+  +--------+--------------------+
                          |                  |
                +---------v------------------v------------+
                |  Memory Decay & Consolidation           |
                |  Exponential decay, idle consolidation   |
                |  HNSW clustering, soft-delete + undo     |
                +-----------------------------------------+
                               |
            +------------------v-------------------+
            |  Daemon (HeartbeatLoop)              |
            |  Cron, file-watch, checklist,        |
            |  webhook, deploy triggers            |
            |  Circuit breakers, budget tracking,  |
            |  trigger deduplication                |
            |  Notification router + digest reports |
            +------------------+-------------------+
                               |
            +------------------v-------------------+
            |  Deployment Subsystem                |
            |  ReadinessChecker, DeployTrigger      |
            |  DeploymentExecutor                   |
            |  Approval gate + circuit breaker      |
            +--------------------------------------+

How the Agent Loop Works

Message arrives from a chat channel (text, images, video, audio, or documents)
Memory retrieval -- AgentDB hybrid search (70% semantic HNSW + 30% TF-IDF) finds the most relevant past conversations
RAG retrieval -- semantic search over your C# codebase (HNSW vectors, top 6 results)
Instinct retrieval -- proactively queries learned patterns relevant to the task (semantic + keyword matching)
Identity context -- injects persistent agent identity (UUID, boot count, uptime, crash recovery state)
Runtime self-improvement layer -- active runtime artifacts (skill, workflow, knowledge_patch) inject internal guidance; shadow artifacts stay evaluation-only
Execution replay layer -- prior same-world success/failure branches are injected before planning retries
PLAN phase -- LLM creates a numbered plan, informed by learned insights and past failures
ACT phase -- LLM executes tool calls following the plan
OBSERVE -- results are recorded; error recovery analyzes failures; failure classifier categorizes errors
REFLECT -- every 3 steps (or on error), LLM decides: CONTINUE, REPLAN, or DONE
Auto-replan -- if 3+ consecutive same-type failures occur, forces a new approach avoiding failed strategies
Repeat up to 50 iterations until complete
Learning -- tool results flow through TypedEventBus to the learning pipeline for immediate pattern storage
Response sent to the user through the channel (streaming if supported)

Provider/model selection semantics: Strada is always the agent talking to the user. Choosing a provider/model does not bypass Strada or send your message directly to that provider. Instead, it sets Strada's primary execution worker. Planning, review, synthesis, routing, and fallback stay inside Strada's current orchestration pool: the configured PROVIDER_CHAIN, plus the actively selected worker if you temporarily switch outside that chain. Strada also keeps ownership of the next step. If a provider returns an incomplete analysis, asks the user what to do next, or makes a broad completion claim without enough evidence, Strada reopens the loop, routes another inspection/review pass, and only returns once the result is verified or a real external blocker remains.

Memory System

The active memory backend is AgentDBMemory -- SQLite with HNSW vector indexing and a three-tier auto-tiering architecture.

Three-tier memory:

Working memory -- active session context, auto-promoted after sustained use
Ephemeral memory -- short-term storage, auto-evicted when capacity thresholds are reached
Persistent memory -- long-term storage, promoted from ephemeral based on access frequency and importance

How it works:

Session history is trimmed with provider-aware thresholds, and trimmed slices are persisted to memory before they leave the active context window
Hybrid retrieval combines 70% semantic similarity (HNSW vectors) with 30% TF-IDF keyword matching
The strada_analyze_project tool caches project structure analysis for instant context injection
Memory persists across restarts in the MEMORY_DB_PATH directory (default: .strada-memory/)
The session summarizer updates task execution memory every 10 active messages and again during session cleanup
Automatic migration from the legacy FileMemoryManager runs on first startup

Fallback: If AgentDB initialization fails, the system automatically falls back to FileMemoryManager (JSON + TF-IDF).

Learning System

The learning system observes agent behavior and learns from errors through an event-driven pipeline.

Event-driven pipeline:

Tool results flow through TypedEventBus to a serial LearningQueue for immediate processing
No timer-based batching -- patterns are detected and stored as they occur
The LearningQueue uses bounded FIFO with error isolation (learning failures never crash the agent)

Hybrid weighted confidence scoring:

Confidence = weighted sum across 5 factors: successRate (0.35), pattern strength (0.25), recency (0.20), context match (0.15), verification (0.05)
Verdict scores (0.0-1.0) update alpha/beta evidence counters for confidence intervals
Alpha/beta parameters are maintained for uncertainty estimation but are not used for primary confidence computation

Instinct lifecycle:

Proposed (new) -- below 0.7 confidence
Active -- between 0.7 and 0.9 confidence
Evolved -- above 0.9, proposed for promotion to permanent
Deprecated -- below 0.3, marked for removal
Cooling period -- 7-day window with minimum observation requirements before status changes
Permanent -- frozen, no further confidence updates

Active retrieval: Instincts are proactively queried at the start of each task using the InstinctRetriever. It searches by keyword similarity and HNSW vector embeddings to find relevant learned patterns, which are injected into the PLAN phase prompt.

Cross-session learning: Instincts carry provenance metadata (source session, session count) for cross-session knowledge transfer.

Goal Decomposition

Complex multi-step requests are automatically decomposed into a directed acyclic graph (DAG) of sub-goals.

GoalDecomposer:

Heuristic pre-check avoids LLM calls for simple tasks (pattern matching for complexity indicators)
LLM generates DAG structures with dependency edges and optional recursive depth (up to 3 levels)
Kahn's algorithm validates cycle-free DAG structure
Reactive re-decomposition: when a node fails, it can be broken into smaller recovery steps

Goal Execution (via SupervisorDispatcher):

Wave-based parallel execution respects dependency ordering
Semaphore-based concurrency limiting (SUPERVISOR_MAX_PARALLEL_NODES)
Failure budgets (SUPERVISOR_MAX_FAILURE_BUDGET) with configurable thresholds
Per-node timeout with AbortSignal propagation to fetch layer
Health-aware provider fallback via ProviderHealthRegistry
Persistent goal tree state via GoalStorage (SQLite) for resume after restart

Tool Chain Synthesis

The agent automatically detects and synthesizes multi-tool chain patterns into reusable composite tools. V2 adds DAG-based parallel execution and saga rollback for complex chains.

Pipeline:

ChainDetector -- analyzes trajectory data to find recurring tool sequences (e.g., file_read -> file_edit -> dotnet_build)
ChainSynthesizer -- uses LLM to generate a CompositeTool with proper input/output mapping and description
ChainValidator -- post-synthesis validation with runtime feedback; tracks chain execution success via weighted confidence scoring
ChainManager -- lifecycle orchestrator: loads existing chains on startup, runs periodic detection, auto-invalidates chains when component tools are removed

V2 enhancements:

DAG execution -- chains with independent steps run in parallel using dependency-aware scheduling
Saga rollback -- when a chain step fails, previously completed steps are undone in reverse order using registered compensating actions
Chain versioning -- chains track version history; old versions are archived, not deleted

Security: Composite tools inherit the most restrictive security flags from their component tools.

Confidence cascade: Chain instincts follow the same confidence lifecycle as regular instincts. Chains that drop below the deprecation threshold are automatically unregistered.

Multi-Agent Orchestration

Multiple agent instances can run concurrently with per-channel session isolation.

AgentManager:

Creates and manages agent instances per channel/session
Session isolation ensures agents on different channels do not interfere with each other
Enabled by default; set `MULTI_AGENT_E

Strada.Brain

README