Phase 11 — Agentic Brain · Autonomous Goal Loop

Institutional memory for
coding agents

TechSphereX Studio is an open-source AI Experience Engine that intercepts agent actions, decomposes goals into User Stories with BA-level analysis, and orchestrates multi-agent workflows with HITL controls — so your agents plan, execute, and learn autonomously.

Get Started View Architecture

Pipeline Layers

MCP Tools

HITL

Human-in-the-Loop

180s

HITL Timeout

CLI Fleet (Claude · AGY · Grok · Codex)

Phase — Agentic Brain

$cd core/techspherex-engine && python -m uvicorn src.main:app --port 8082

INFO: Started server process

INFO: Loading sentence-transformer: all-MiniLM-L6-v2

INFO: Qdrant connected at localhost:6333

INFO: Agent registry initialized (TTL=120s)

INFO: SSE event bus ready

INFO: GoalStore (SQLite WAL) → ./data/goals.db

INFO: BAService + NotificationService (flag OFF) initialized

INFO: Goal service (Phase 11 Agentic Brain) initialized

INFO: MCP server bound on stdio (15 tools)

INFO: Uvicorn running on http://0.0.0.0:8082

—————————————

$curl http://localhost:8082/health

{ "status": "ok", "qdrant": true, "embedder": true, "llm": true }

Built for production agent workflows

Every component in TechSphereX Studio is designed to make your AI agents smarter over time.

3-Layer Intercept Pipeline

Every agent action flows through L1 keyword filter, L2 semantic vector search via Qdrant, and L3 LLM synthesis — returning ranked experience suggestions in milliseconds.

FastAPI · Qdrant · Ollama

Harness Brain Orchestration

Submit a high-level goal and the engine decomposes it into Research, Code, Test, and Evaluate tasks, assigns them to agents by role, and closes the loop with PostTool feedback.

Phase 9 · GoalService · TaskRecord

Agent Registry

In-memory registry with 120-second TTL tracks online agents by role — orchestrator, research, coding, testing, evaluation — and routes tasks to the right agent automatically.

AgentRegistry · Heartbeat · Role routing

MCP Integration

15 built-in MCP tools expose the full engine surface — intercept, save experience, register agent, submit goal, claim task, and complete task — to any MCP-compatible client.

FastMCP · stdio transport · 15 tools

SSE Real-time Event Bus

Agents subscribe to /api/stream/{id} and receive push events — task_assigned, goal_completed, experience_evolved — without polling.

sse-starlette · asyncio.Queue · push

Native Desktop Dashboard

React 19 + Tauri 2 app with nine pages — Dashboard, Experiences, Agents, Goals, Fleet, Monitor, Graph, Terminal, Settings — with Notification config (webhook + Telegram feature flag) built-in.

React 19 · Tauri 2 · Vite 6

Agentic Brain — Phase 11

BA Agent decomposes any natural-language goal into User Stories with Acceptance Criteria and Fibonacci story points using LLM. Tasks are queued by priority, claimed exclusively (no race condition), and executed autonomously. HITL tasks wait 180 seconds for SA approval — then auto-execute. SECURITY tasks require explicit approval always. Interrupted tasks resume from checkpoint, not from scratch.

BA Agent · User Stories HITL · 180s timeout SQLite WAL · Resume from checkpoint Fibonacci 1,2,3,5,8,13 Webhook · Telegram (v2)

Architecture overview

Polyglot monorepo — Python for the engine, TypeScript for the SDK and desktop, Rust via Tauri for native packaging.

Intercept Pipeline

Filter

Keyword & readonly guard

→

Semantic Search

Qdrant vector retrieval

→

LLM Synthesis

Ollama / llama.cpp

→

Out

InterceptResponse

Ranked suggestions

Engine (Python · :8082)

domain/

ExperienceService, GoalService, EvolutionService, Ranker, JudgeService

DDD

infrastructure/

QdrantStore, Embedder, AgentRegistry, EventBus, BackgroundWorker

Qdrant v1.17+

presentation/

IntercceptRouter, AgentsRouter, GoalsRouter, StreamRouter, MCPServer

FastAPI

Client (TypeScript)

apps/techspherex-desktop

React 19 dashboard — 9 pages with real-time SSE and Tauri sidecar

Tauri 2

packages/techspherex-client

TypeScript SDK — sync/async intercept, agent_loop helper, offline queue

tsup

apps/techspherex-cli

CLI — status, list, add, search, delete, export, import

Turborepo

Fleet & Host Services

apps/cli-bridge · :8083

Python host-side proxy — spawns CLI subprocesses, streams results back to engine

Flask

apps/cli-bridge/agent_loop.py

Polls engine every 15 s — claims tasks, dispatches to CLI, reports completion

asyncio

CLI Fleet

Claude · AGY · Grok · Codex — each wrapped with fleet-hooks that report busy/idle status in real time

hooks

Daily workflow: .\start.ps1 → engine + bridge + loop + dashboard all start → submit goal in UI → tasks flow to fleet → CLIs execute autonomously → .\stop.ps1 when done (Docker keeps running)

Quick start

Docker engine already running at :8082? One command starts everything else.

Install dependencies

Run once after cloning to install Node packages and create the CLI Bridge virtual environment.

npm install

Set up CLI fleet (run once)

Auto-detects Claude, AGY, Grok, Codex paths and configures fleet hooks in PowerShell profile + Claude settings.json.

.\scripts\cli-setup.ps1

Start everything

Starts CLI Bridge (:8083), Agent Loop, and Dashboard (:5173). Engine Docker is detected — skipped if already running.

.\start.ps1

Open Dashboard

Browse to the management UI. Submit a goal in Goals, watch CLIs execute in Fleet.

http://localhost:5173

Stop when done

Stops bridge, agent loop, and dashboard. Docker (Engine + Qdrant) keeps running.

.\stop.ps1

Install dependencies

Install Node packages from the repo root.

npm install

Start everything

Starts CLI Bridge (:8083), Agent Loop, and Dashboard (:5173) as background jobs. Engine Docker detected — skipped if already running.

bash start.sh

Open Dashboard

Browse to the management UI — Goals, Fleet, Experiences, Agents, Monitor.

http://localhost:5173

Run one-shot CLI setup

Auto-detects Claude, AGY, Codex, Grok paths and writes hooks to PowerShell profile + ~/.claude/settings.json. Safe to re-run — never duplicates entries.

.\scripts\cli-setup.ps1

Reload PowerShell profile

Activates the new agy and codex function wrappers in the current session.

. $PROFILE

Verify fleet in Dashboard

Open Fleet page — all configured CLIs should show Online within 30 s of starting the engine.

http://localhost:5173/fleet

What the setup configures:
• apps/cli-bridge/config.json — correct paths for each CLI
• PowerShell $PROFILE — agy / codex wrappers with fleet reporting
• ~/.claude/settings.json — UserPromptSubmit / Stop / PreToolCall hooks
• Grok: edit ~/.grok/config.toml manually (see README → CLI Setup)

Initial deploy (build + start)

Builds Docker image from source, starts Engine (:8082) + Qdrant (:6333). Polls /health up to 90 s, runs smoke test.

.\scripts\deploy\deploy-docker.ps1

Hot-patch code changes

Copies src/ into the running container and reloads uvicorn in seconds — no rebuild needed.

.\scripts\deploy\update-engine.ps1

Deploy with latest git changes

Pulls latest commits, rebuilds image, restarts container — volumes (experiences, goals) are untouched.

.\scripts\deploy\deploy-docker.ps1 -Pull

Verify health

Confirm the engine is up and all subsystems are ready.

curl http://localhost:8082/health

API reference

The engine runs on port 8082. All endpoints return JSON.

Method	Endpoint	Description
POST	/api/intercept	3-layer pipeline — returns ranked suggestions
POST	/api/posttool	Report PostTool verdict — closes the learning loop
GET	/api/experiences	List all stored experiences
POST	/api/experiences	Save a new experience
POST	/api/experiences/search	Semantic vector search
POST	/api/agents/register	Register an agent with role and capabilities
GET	/api/agents	List online agents (TTL-filtered)
POST	/api/goals	Submit goal — engine decomposes into 4 tasks
POST	/api/goals/{id}/tasks/{tid}/claim	Agent claims a task
POST	/api/goals/{id}/tasks/{tid}/complete	Complete task — triggers SSE broadcast
GET	/api/stream/{agent_id}	SSE stream — subscribe to push events
POST	/api/evolve	Trigger evolution cycle — promote/demote experiences
GET	/health	Liveness probe
GET	/api/stats	Engine statistics — queries, latency, experience count
Phase 11 — Agentic Brain
POST	/api/ba/analyze	BA Agent decomposition — returns User Stories + AC + Fibonacci points
POST	/api/ba/goals/{id}/tasks/{tid}/approve	SA approves or rejects a HITL task
POST	/api/ba/goals/{id}/tasks/{tid}/checkpoint	Save task checkpoint for resume-on-interrupt
GET	/api/ba/notifications/config	Get notification config (feature flag + webhooks)
POST	/api/ba/notifications/toggle	Toggle notification feature flag ON/OFF (via UI or MCP)

Daily workflow

From session start to autonomous execution — four steps, one command each.

Start services

.\start.ps1

Engine detected → skip. Bridge, Agent Loop, Dashboard start in background.

Submit a goal

localhost:5173/goals

BA Agent decomposes into User Stories + Fibonacci points. HITL tasks await approval.

Fleet executes

localhost:5173/fleet

Claude, AGY, Grok, Codex claim tasks autonomously via SSE push. Results flow back to engine.

Stop & persist

.\stop.ps1

Bridge + dashboard stop. Docker keeps running. Experiences and goals survive restart.

Running services

All services started with .\start.ps1. Docker Engine + Qdrant run persistently.

Engine API

localhost:8082

FastAPI — 3-layer pipeline + Agentic Brain

Swagger Docs

localhost:8082/docs

Interactive OpenAPI documentation

Qdrant

localhost:6333

Vector database for experience embeddings

CLI Bridge

localhost:8083

Host-side proxy — spawns CLI subprocesses

Dashboard

localhost:5173

React 19 — 9 pages, real-time SSE fleet view

Institutional memory forcoding agents