Agent Foundry

The Agent Foundry turns Cortexa from a memory engine into a build engine. You compose your own hierarchy of agents — an entry "architect" over specialist sub-agents, each with its own persona, skills, and tools — bundle them into a Kit, and hand it an idea. The Foundry runs a four‑phase pipeline that thinks with your encrypted vault and acts through real coding agents (Claude Code, Codex) or API codegen, then keeps iterating — autonomously or via chat — until the build is right.

It's built on the same primitives as the rest of Cortexa: the durable job queue, the tool registry, the orchestrator's DAG executor, and the encrypted vault. Agents, skills, tools, and kits are all stored as encrypted, syncable data.

The building blocks

Block	What it is
Agent	A worker with a system prompt (persona), a tool subset, attached skills, an exec mode, and (for entry agents) sub‑agents to delegate to.
Sub‑agent	A specialist an entry agent delegates to. The hierarchy is Agent → sub‑agent → tool / skill and is kept acyclic.
Skill	Reusable applied know‑how — instructions woven into an agent's prompt during a run (e.g. "Write idiomatic Rust").
Tool	A callable capability. Built‑in tools ship with Cortexa; custom tools are prompt‑tools you define (name + description + system prompt).
Kit	A runnable bundle: an entry agent, member agents, a project‑wide system prompt, concept slots, and an output directory.
Concept slot	A document the build should produce (e.g. Combat_system), routed to the specialist that drafts it. Optional slots are selected per idea.
Build Run	One execution of a kit against an idea, advancing through the pipeline with a live log and its own chat thread.

Everything is editable in the Agent Foundry tab (Workspace · Agents · Skills · Tools · Kits), and you can lean on ✨ AI to draft any prompt or description. Power‑user shortcuts: Alt+1…5 jump between the tabs, and Ctrl/⌘+Enter in the idea box starts a build.

Build workspace

Use New build to write your brief, choose a kit, set memory scope, and choose the number of passes. Expand Team & workflow to inspect the team and its learning scorecards. Switching to Runs keeps your draft intact.

The overview cards open runs that are in progress, awaiting review, or completed. Counts cover the latest 50 runs loaded into the workspace. In Runs, combine status filters with a search by brief, kit, or phase. Starting a build opens its expanded run card; approval, live chat, scheduling, output files, comparisons, and full-screen monitoring remain available.

Generate a kit from an idea

You can start in Ask Cortexa: ask it to design a Foundry kit for your idea. The assistant saves a draft in the conversation with a Review in Foundry button. Open that draft, choose Create kit, then go to Workspace → New build. Your new kit and original brief are selected there; Start build begins execution.

Full kit generation can take several minutes. Foundry shows the current design stage, and you can switch to other views while it works without losing the pending draft. Drafts in Ask remain in encrypted conversation history; unsaved drafts in Foundry remain available until you close or restart the app.

Don't want to wire a team by hand? On the Kits tab, describe what you want — "a kit that turns a blog topic into a researched, fact‑checked, SEO‑ready article" — and AI designs the whole kit for you: an entry agent, specialist sub‑agents, custom tools, skills, and concept slots, all cross‑wired (sub‑agents, tool/skill attachments, and slot authors resolved automatically).

It's a multi‑pass design: one call lays out the structure and wiring, then follow‑up calls flesh out each agent's persona, each tool's behavior, and each skill's instructions. You get a draft preview — the agent tree, tools, skills, and slots — with Create · Regenerate · Discard. Nothing touches your library until you click Create, and the new kit opens straight in the editor so you can tweak anything. Generated agents default to thinking mode, so the kit runs immediately without an external CLI.

You can also build a kit from a thought: on any vault item, click Build a kit and the generator seeds itself with that thought's text — it jumps to the Kits tab and drafts a kit around what you already captured.

The pipeline

A Build Run advances through four phases (with a fifth, iterative phase on top):

idea + kit
   └─▶ Intake      — each specialist drafts its concept docs
   └─▶ Vet         — feasibility is scored (with an approval gate)
   └─▶ Plan        — the architect breaks the design into tasks
   └─▶ Orchestrate — Claude Code / Codex build it (or API codegen)
   └─▶ Refine ∞    — re-read the build, improve; or chat to direct it

• Intake drafts the selected concept slots in parallel, each routed to its specialist agent's persona; the docs are captured as encrypted vault items.
• Vet scores buildability 0–1. Below your threshold it pauses for approval (unless auto‑approve is on).
• Plan turns the vetted concept into a build task graph.
• Orchestrate builds each task. With external execution on, it spawns the coding agent headless in an isolated git worktree (the concept docs are materialized to ./concept/); otherwise it uses API codegen. Artifacts are captured back to the vault.

Reading a run at a glance

Each run card leads with a legible lifecycle badge — Queued · Running · Evaluating · Needs approval · Stopping · Done · Failed — distilled from the fine‑grained phase, so you can tell a run's state without parsing the log. Expand a card and it surfaces what the engine actually did:

• the phase stepper + live activity timeline,
• the Plan Inspector — the orchestration plan the architect produced (pretty‑printed),
• the verify verdict for CLI builds (✓ verified / ✗ not verified, with the number of fix attempts the closed verify loop spent),
• a note when an iterating run converged (stopped because recent passes produced no change),
• and the run's memory scope (see below).

Iteration & chat

A Build Run can keep going:

• Iteration loop — choose 1, 5, 10, 20, or ∞ passes. Each pass re‑reads the entire build so far (its memory) and produces the highest‑impact improvement. Stop any time.
• Per‑build chat — every build has its own conversation. Send a directive ("add a boss fight", "make the UI dark") and it runs one targeted pass that applies your request. The assistant reply is a real summary of what the agent did — for CLI builds it surfaces the coding agent's own account of the change plus the list of files it touched (git‑derived), not a generic "applied your change". Works whether the build is idle or mid‑run.
• Resume iterating — a finished build isn't frozen. Expand it and choose 5, 10, 20, or ∞ more passes, then Resume iterating to re‑arm the autonomous loop right where it left off.

Passes are serialized per run (one at a time, even across Cortexa's parallel workers) and re‑driven by a background sweep, so the autonomous loop keeps advancing and a chat directive sent mid‑pass is reliably picked up — never lost or applied twice.

The pipeline log streams live, so you can watch each step as it happens.

Scheduled builds & the master gate

Builds can run unattended on a timer:

• Per‑run schedule — arm a finished run to resume for N more passes every X hours, or daily at a set local time.
• Per‑kit schedule — a whole kit can wake on its own cadence and push its latest run a few passes further (seeding a fresh build from a saved idea if it has none yet).

Two global controls in Control → Settings → Agent Foundry govern all of that scheduled work at once. Both gate only the start of a new scheduled pass — a run already in flight always finishes (so a long, even 24‑hour, build that began in time is never cut off):

• Pause scheduled builds (master kill switch) — flip it on and no kit or per‑run schedule starts another iteration. Turn it back off and everything resumes on its normal cadence. Manual builds and chat directives are unaffected.
• Only start scheduled builds during a daily window — restrict scheduled starts to a local‑time window, e.g. 00:00–05:00 for overnight work. An end earlier than the start wraps past midnight (22:00–05:00). Outside the window, due passes simply wait until it next opens.

Neither touches reflection, dreams, cognition, or the daily briefing — it's scoped to Foundry builds. (Manual builds you start yourself always run regardless of either control.)

Memory scope: cold, project, or full bank

How much of your vault a run grounds against is an explicit, sticky control in the Build composer — the choice is unmistakable and persists across sessions:

• Cold — excludes retrieved vault memory. The build still receives the idea, kit instructions and any integration-source snapshots you explicitly selected.
• Project — retrieved vault items are hard-filtered to the selected project after the globally bounded candidate search. This keeps out other projects, although a busy vault can cause relevant project items to miss the initial candidate set.
• Full bank — agents draw on the whole vault, pulling in relevant prior work across every project.

Scope is independent of which project a run's output is stamped to. Every run card shows its scope, so you always know what the agents could see.

Expanded run cards include Memory used receipts for traceable packets. Each receipt preserves the excerpt and review state seen by that phase, then separately shows the item's current local state. Reviewing, disputing, replacing, editing, trashing, or deleting a thought later cannot rewrite what the historical build saw; unavailable items do not reveal stored historical plaintext. A disputed or replaced memory is excluded from the next packet before ranking, while its prior receipt remains an audit record.

Cold vs memory‑assisted (A/B)

Choose ⇄ Cold vs assisted in the Build composer to launch the same idea twice as a paired run group: one cold run with no retrieved vault memory and one memory‑assisted run using the project or full bank.

A completed pair appears as an Observed difference. The table compares model-rated feasibility in percentage points, passes, verification, artifact counts, tokens, and estimated cost. Artifact count is a neutral quantity rather than a success measure. Verification and usage stay unknown when the run has no recorded value; Cortexa does not display missing data as zero.

The comparison is available only when a group contains exactly one cold run and one assisted run and both finish. Pending, failed, incomplete, and duplicate groups stay visibly unfinished as Comparison unavailable. Each comparison links to both runs, where you can inspect the run details and Memory used receipts.

This pair does not isolate memory's effect. Model behavior, source snapshots, prompts, and live memory can drift between ordinary runs, so the card describes the recorded difference without claiming that memory caused it.

Controlled memory evaluation

Foundry's ordinary paired cards remain observational. Cortexa also includes an offline coding benchmark for separately controlled, independently scored single-pass experiments. It freezes one strict context packet per task, keeps hidden cases out of model requests, and runs generated code inside a bounded non-root container.

Passing the harness tests means the evaluation machinery works. It does not show that memory improves outcomes. A performance conclusion requires a preregistered, reviewed held-out suite and the decision rules in the evidence-backed memory pilot runbook. That runbook also keeps real multi-tool coding-agent productivity as a separate future evaluation rather than inheriting a claim from single-pass results.

Learning across runs

The Foundry attributes every run's outcome back to the agents that drafted it, and surfaces that learning under Workspace → New build → Team & workflow:

• Agent scorecards — per authoring agent on the selected kit: runs, pass rate, average feasibility, and fix attempts. See which specialists are pulling their weight.
• Prompt‑evolution history — expand an agent to see its prompt‑version timeline: each version it ran under, the reason it changed (baseline · evolved · ablation rollback), and that version's pass record. With auto‑evolve on, the Foundry rewrites a weak authoring agent's prompt after a failed verify — or rolls back to a prior version that performed better — and this is where you watch it happen.

Usage, cost & output size

Every Build Run is metered, and the Foundry shows you exactly what each kit and each agent is spending — always on, no toggle.

• Tokens — input and output tokens are tracked for every generation in the pipeline (intake, vet, plan, orchestrate, refine, evolve, verify) and rolled up per kit and per agent. CLI builds count too: Claude Code runs report their own token usage and cost, which are captured alongside the API‑provider calls.
• Generations — how many model calls each kit/agent has made (and how many failed).
• Estimated cost — a dollar estimate from a per‑model price table (Claude, OpenAI, Gemini, MiniMax; local Ollama models are free). For CLI builds the agent's own reported cost is preferred. The estimate is stored per generation, so historical totals stay stable even when prices change later.
• Output size — each run records the artifacts it produced (count + total characters of the generated docs/code) and, for code‑gen/CLI builds, the on‑disk output (file count + bytes of the build directory).

Where it shows up:

• Kit cards (Kits tab) carry a stats strip: runs · tokens · generations · est. cost · output size.
• Agents (Agents tab) show a tokens / generations / cost badge, so you can see which specialists are doing the expensive work.
• Build Runs show a per‑run token/cost/size line, and expanding a card reveals a usage drill‑down — calls / tokens / cost broken out by phase (intake → refine, chronological) and by agent, so you can see exactly where a run spent its budget.

Runs that predate this tracking still report their run counts and output size; token/cost history begins when the feature landed. Headless callers can read the same rollups via the foundry_stats MCP tool.

External execution & safety

External execution is off by default and double‑gated. Enable it in Build → Execution:

1. Enable Agent Foundry — lets Build Runs execute.
2. Allow external coding agents — permits spawning Claude Code / Codex subprocesses.
3. Let agents edit files autonomously — adds --dangerously-skip-permissions so the CLI can write files without prompting.

Guardrails: a CLI allowlist, a per‑run subprocess budget, a wall‑clock timeout, recursion‑depth limits, and git‑worktree (or isolated‑dir) isolation per run. Each kit chooses its output directory; a build that targets a git repo gets a per‑run worktree.

⚠️ With external execution + autonomous edits enabled, the Foundry runs real coding agents that write files and run commands. Only point it at build targets you trust.

Resilience

• Crash‑safe — Build Runs use the durable job queue. A reaper resumes any run left in a non‑terminal phase — both at startup (after a crash/quit) and periodically while running, so an autonomous loop or a queued chat directive always keeps moving.
• Openable — each Build Run card has an Open files button that opens the run's on‑disk build folder (its git worktree or scratch dir) in your file manager. A run that built in‑app (API/thinking mode) has no disk folder, so it offers to open its vault artifacts instead.
• Deletable — deleting a build removes its record and wipes its on‑disk output folder (scoped to that run's hash), after a confirm dialog that shows the exact path. If the build is deployed to the Hive, it also offers to take the live deployment down.

Selected integration sources

Use Find integrations in Ask beside a build brief to find relevant Loom sources. Return with Use selected sources in Foundry, or review an Ask-generated kit draft that retains its selected sources. Source chips can be removed before starting. This handoff preserves the build's memory scope.

At build start, Foundry loads up to two captured excerpts per selected source and includes a bounded snapshot in the brief. These are explicit inputs, including in No memory mode, rather than a live connection. A deleted source, unavailable worker, or source with no captured content stops the start with an actionable message. Sync and review the source in Loom or remove it before retrying. The build's normal artifact sharing and deployment settings apply to its output.

Deploy a build to the Hive

Ship a finished Build Run's output as a live, browsable artifact on your Hive relay. Each run card has a Deploy button (needs a Hive admin token on a connection, same as auto‑publish); it returns a public URL at /app/<run-id>/.

The relay adapts to the output's shape — set the kit's Deploy output as (or override per deploy):

• Site — the output has an index.html: served as a live, playable web app / game.
• Docs — markdown/reports: rendered to a readable page.
• Files — anything else: a clean download landing page.
• Auto — inferred from the tree (root index.html → site; .md → docs; else files).

For API-generated builds, Auto and Site extract complete HTML pages from Markdown code fences when no root index.html exists. One page opens directly; multiple pages get a landing page linking to each runnable artifact. This also works when redeploying an older build. The original Markdown files remain available, and explicit Docs / Files modes keep their original behavior. HTML snippets and incomplete documents are not treated as runnable pages.

Build‑to‑static. Framework projects (Vite, React, etc.) are built before shipping — npm install && npm run build runs and the produced dist//build//out/ is what's served, so deploys are runnable rather than raw source. Override the build command + output subdir per kit for pnpm/yarn/monorepos. A pure server app (only npm start/dev, no static build) is flagged rather than deployed broken. The build runs only when external execution is enabled.

Auto‑deploy. Toggle Auto‑deploy after each iteration on a run and every completed pass re‑publishes to the same public URL — combine it with scheduled builds for a project that improves itself and keeps its live link current. You can also arm it per kit (the Auto‑deploy each iteration checkbox in the Kit editor): every new run of that kit then starts with auto‑deploy on, so you don't have to remember to flip it each time. (The kit toggle is just the default for new runs — each run can still override it.)

Sandboxed. Deployed apps are served with a CSP that allows CDN assets (over https:) but blocks all network egress (connect-src 'none') — an untrusted build can't call the relay's admin APIs or exfil data. Secret files (.env, keys, .npmrc) are never shipped.

Portable kits

Export a kit — with all its agents, sub‑agents, skills, and custom tools — to a single JSON bundle, and import it anywhere. Import is non‑destructive: agents and the kit get fresh ids, while skills and tools are reused by name so you don't accumulate duplicates. Sharing a whole agent team is one click. (Built‑in tools are referenced by name and assumed present on the target.)

Sync across machines over the Hive

Beyond file export, you can push Foundry entities straight over the Hive so they sync to your other machines automatically. Hit Share to Hive on a kit (it bundles the kit with its agents, skills, and custom tools) or on a standalone agent, skill, or tool, and the receiving instance imports it with deterministic ids — re‑sharing an edited kit updates the existing copy in place instead of duplicating. It rides the same encrypted, reliable item‑sync path as your thoughts; no relay changes needed.

The Game Maker kit

Cortexa ships a built‑in example: the Game Maker kit — a "Game Architect" entry agent over 11 domain specialists (core concept, runtime, controls, physics, gameplay, UX, world, progression, technical, networking, balance) and ~46 concept slots auto‑routed to the right specialist. Use it as‑is, clone it, or build your own kit (a research kit, a startup kit, anything).

Build Router — thoughts into builds

With the Build Router on (off by default; enable it in Control → Build Router, requires Agent Foundry), a captured thought that asks to build something is turned into a Build Run automatically — no need to open the Foundry. It works from any of your own capture paths, including Telegram voice notes.

How it decides:

1. Cheap pre‑filter. A thought is only considered when it contains a build signal — a built‑in set (build, kit, make a, create a, prototype, scaffold, …, matched on word boundaries so rebuilding/builds don't trip it) plus any custom trigger phrases you add. The built‑in signals mean natural phrasing like "use the game kit to build this" is caught without exact wording.
2. LLM classifier. Only matching thoughts go to an LLM, which decides whether it's really a build request, distills a clean idea, and routes it to the best existing kit — authoring a new kit when none fits.
3. Build. It starts the run (inheriting the kit's auto‑deploy default), and for Telegram‑origin thoughts replies when the build finishes. Turn on Global kit publish to auto‑deploy routed builds and send back the public URL.

The router never re‑routes its own generated output, and only runs on your own captures — synced Hive peer thoughts don't trigger builds.

MCP tools

The Foundry is also driveable headlessly via MCP: foundry_define_agent, foundry_define_kit, foundry_seed_game_kit, foundry_run, foundry_approve_run, foundry_get_run, foundry_stats (per‑kit and per‑agent token/cost/generation/output rollups), and more — so an external agent can author, launch, and monitor builds programmatically. foundry_define_kit does a non‑destructive update when given an existing id: fields you omit (agents, slots, deploy + schedule config) are preserved, so you can flip one setting — e.g. auto_deploy — without re‑sending the whole kit. foundry_list_kits shows each kit's auto-deploy / iterate state.