Measured, not claimed.
A self-evolving research-agent platform: a team of agents that rewrites its own genomes, judged by a referee it can't see.

_{▶ Watch the full demo on YouTube · simulated data · try it locally with ?demo=film or the endless ?demo=live}

Most research agents do what they are told once. Silk Lab's teams get better at the work, and have to prove it. A master agent turns a user's research goal and uploaded data into a design (team, tasks, locked success criteria), deploys a team of sub-agents, and then runs an evolution loop — review → mutate (annealed edit budget) → safety review → validate → gate → keep or roll back — in which agents rewrite their own genomes (prompts, modular node graphs, tools, memory policy). An independent referee owns the criteria and a held-out task set the agents never see, so every "improvement" is measured, not claimed.

The demo video, product film and promo run on simulated data (frontend demo mode); they show the product flow, not live results.

Why Silk Lab is different

Built for three problem statements of The Recursive Agents Hackathon:

🧬 Version N+1 (primary)	Each accepted mutation produces a new genome version with lineage, evidence chain and a held-out comparison against the baseline (POST /api/evolution/{goalId}/final).
✅ Done Means Done	Success criteria are locked by the referee before work starts; a live task board (start/complete/fail/strike-replace) and user decision requests make completion explicit and auditable.
🧠 Shared Brain	Agents share an Obsidian-vault + Qdrant memory with access policies, a shared workspace with locks, and an agent message bus inside a configurable team topology.

A research lab, piece by piece

🗺️ The canvas: master, team, lab

The master agent runs an internal council (planner / coordinator / criteria committee vote), a chat module (Jev triage) and a prep phase (uploads, web, design), then deploys the team with a long press. Teams follow a configurable topology: hierarchy, groups and edges, EACH · ALL · K_OF_N · BATCH activation, sync/async, timeouts and triggers.

🧩 Inside an agent: modular nodes, traced end to end

Every agent is a graph of modular nodes: LLM, Jev decision, code, tool, lab instrument, memory read/write and sub-agent call nodes, each a versioned entry in a shared module catalog. The master agent composes them freely: it deploys each sub-agent from a template graph, edits any genome through AgentFactory (safety-reviewed), and its evolution loop adds, removes, rewires and reuses modules (ADD_NODE · REMOVE_NODE · REUSE_MODULE) or writes new code modules.

Each node and the whole workflow are traced. Every node execution is its own span (agentId/geneId) inside the run's trace; every workflow run is an idempotent agent_run record with cost and duration; the canvas shows per-node calls/min, latency, failures and the node's own evolution history (GET /api/agents/{id}, GET /api/monitor/trace/{traceId}). Evolution evaluates every candidate through this same traced runtime, so each keep or rollback rests on recorded runs: score, per-category results and cost ratio against the parent, stored in the evidence chain alongside the genome's lineage.

🔁 Evolution: only measured gains are kept

Agents are genomes: prompts, node graphs, tools and memory policy, stored with lineage and lifecycle. The evolution loop is multi-objective and can grow multiple trees; every keep or rollback carries its evidence chain and a held-out comparison owned by the referee.

📊 Insights: every call traced and metered

Every LLM and tool call goes through MonitorBus: spans, an SSE stream, traffic and cost metering, cache-hit stats, a 3D memory graph and workspace files.

Architecture

flowchart TB
  user([User]) --> api[api: REST + SSE]
  api --> master[master: council + chat module + prep phase]
  master --> factory[agent: AgentFactory]
  master --> evo[evolution: EvolutionEngine]
  master --> topo[topology: TeamTopology engine + triggers]
  factory --> genome[genome: Genome / ModuleCatalog / lifecycle]
  topo --> runner[runtime: AgentRunner / node graph executor]
  runner --> llm[llm: LlmGateway Crusoe+Jev]
  runner --> mem[memory: Obsidian + Qdrant]
  runner --> lab[lab: LabRegistry + Docker sandbox]
  runner --> ws[workspace: private + shared w/ locks]
  llm --> prompt[prompt: PromptLibrary]
  evo --> referee[safety.referee: locked criteria + held-out]
  factory & prompt & lab & topo & evo --> gate[safety: SafetyGate rules+Jev+LLM]
  subgraph observability
    monitor[monitor: MonitorBus]
  end
  runner & llm & mem & lab & topo & gate & master --> monitor
  api --> tasks[tasks: TaskBoard + decisions]

Loading

Each package has its own README.md; the full design is in docs/DESIGN.md.

Packages (ai.silklab.*)

Package	Responsibility
common	Ids, Actor, ErrorCode/SilkException, Json (canonical serialization + sha256), Backoff, SilkProperties, audit.RevisionLog
monitor	MonitorBus/Span/MonitorStats; async batched persistence, ring buffer, subscriptions
llm	LlmGateway: Crusoe and Jev clients, structured output validation with 3 retries, model/price registry, traffic and cost metering, cache-hit stats
prompt	PromptLibrary: versions, call counts, rendering (stable prefix first, variables by volatility), safety-reviewed proposals, seed prompts
safety	SafetyGate: hard-coded rules + Jev pre-screen + LLM review; safety policy; safety-officer chat; protected paths
safety.referee	Referee: locked criteria, held-out tasks (referee-only storage), scoring, favoritism monitoring; no shared memory
genome	Genome storage/lineage/lifecycle, module catalog (ADAS archive), MemoryAccessPolicy
agent	AgentFactory (master only): create/edit/delete sub-agents and self-edit, all safety-reviewed
runtime	Node runtime: Node types, graph executor, AgentRunner, idempotent run records
topology	Team topology (hierarchy/groups/edges, EACH·ALL·K_OF_N·BATCH activation, sync/async, timeouts), triggers (schedule/listen/batch), deduplicating agent message bus
memory	MemoryService: Obsidian vault, Qdrant index, HashingEmbedder, permissions, expiry/compaction, graph view, custom backends
workspace	WorkspaceManager: path confinement, shared-area read/write locks + file locks
lab	LabRegistry (concurrency policy, queueing, idempotency, timeouts), DockerSandbox, built-in lab tools
tasks	Live task board (4 daily operations + restructuring during conversation), user decision requests
api	REST + SSE: monitor stream, usage/cost, memory graph, workspace files, task board, decisions, safety settings
master	Master agent: internal council (planner/coordinator/criteria committee vote), chat module (Jev triage), prep phase (uploads/web/design), long-press deploy
evolution	Evolution loop: review → mutate (annealed edit budget) → safety review → validate → gate → keep/rollback; multi-objective, multiple trees; evidence chain

🔬 Applied use case: Kwon Lab

Kwon Lab (low vision, Northeastern University), PI Prof. MiYoung Kwon: the team brings gaze-contingent PRL training to VR headsets and tablets. Agents classify eye-movement events, simulate degradations, run the gaze-contingent display and model the visual field. It ships with mock eye tracker, headset and display devices (sim-eye-tracker-lab, sim-vr-headset, sim-gaze-display). Mock data parameters are drawn from the lab's papers (see Credits and citations); how the demo uses them: docs/references.md.

What the lab would get: project report (PDF) · simulated run report — deliverables (headset eye-movement classifier, pre-train/fine-tune pipeline, latency validation, degradation simulator, PRL tracking, hardware test reports, knowledge base, audit trail) with figures and raw data — and the impact hypothesis: pain points, expected gains and a pilot plan to measure them.

💛 Thank you, sponsors

	Powers in Silk Lab
NVIDIA Nemotron	Every role in the team: master, council, sub-agents, referee panel judges and vision. Details: docs/nemotron.md.
Crusoe Managed Inference	The inference endpoint behind the LlmGateway. Calls are wired, but our org currently returns 402 until billing is enabled.
You.com	web-search lab tool for sub-agents; works keyless via the free You.com MCP endpoint.

Models and integrations

• Crusoe Managed Inference (ids confirmed via /v1/models): nvidia/NVIDIA-Nemotron-3-Super-120B-A12B (master, council, evolution reflection; thinking on), nvidia/Nemotron-3.5-Lightning-30B-A3B (sub-agent workhorse; thinking off), nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B (referee panel judges, own rate-limit bucket), nvidia/Nemotron-3-Nano-Omni-Reasoning-30B-A3B (vision role), deepseek-ai/Deepseek-V4-Flash (referee / safety review, a different model family from the master), openai/gpt-oss-120b (structured). The org returns 402 until billing is enabled. Details: docs/nemotron.md.
• TypeSafe: Jev (safety pre-screen and chat triage).
• You.com: web-search lab tool for sub-agents (with YDC_API_KEY via the Search API, otherwise keyless via the free You.com MCP endpoint); safety-gated, results saved as cited SOURCE notes.
• NVIDIA Nemotron Nano Omni: vision.describe lab tool sends workspace images (e.g. gaze plots) as multimodal parts; tested against mocks only.
• NVIDIA OpenShell / NemoClaw: installed and gateway running in WSL with a Silk Lab policy (scripts/nemoclaw/), but not integrated: sandbox creation is blocked on this machine, so agent-written code still runs in Silk Lab's own Docker sandbox. Details: docs/nemoclaw-youcom.md.

---

Getting started

Requirements

• Java 21+, Maven, Docker.
• Node.js and npm for the frontend.
• API keys: CRUSOE_API_KEY and TYPESAFE_API_KEY (optional YDC_API_KEY). Not needed for demo mode.

Quick start

UI only (no backend, no keys)

cd frontend && npm install && npm run dev   # http://localhost:5173
# demo mode with mock data: http://localhost:5173/?demo=film
# endless booth loop (live data flow, bounded memory): http://localhost:5173/?demo=live   (&tour=1 cycles the camera, &speed=2 faster)

Full stack

docker compose up -d                 # MySQL on :3307, Qdrant on :6333
cp .env.example .env                 # set CRUSOE_API_KEY and TYPESAFE_API_KEY
mvn -DskipTests package
java -jar target/silk-lab-*.jar      # http://localhost:8080, check GET /api/health
cd frontend && npm install && npm run dev   # http://localhost:5173 (proxies /api to :8080)

The frontend is Vite + React + TypeScript with a research-instrument design — see frontend/DESIGN.md.

Multi-computer lab

Run the backend with server.address=0.0.0.0; every researcher opens the same URL from their machine and identifies with the researcher switcher (X-Silk-Researcher); lab machines register with scripts/lab-node-agent.sh.

Demo

demo/ contains a genomic regulatory element task: classify 251-bp human DNA sequences as promoter vs non-promoter (150 balanced sequences from Genomic Benchmarks human_nontata_promoters). Agents start with general research, coding and planning skills plus a platform manual (seeded as linked knowledge-graph notes and skills, retrieved on demand) but no genomics knowledge; the script drives the whole flow and prints baseline vs evolved held-out accuracy. API keys are required for the LLM-dependent steps.

./demo/run-demo.sh                                           # bash
powershell -ExecutionPolicy Bypass -File demo\run-demo.ps1   # Windows

Product film and promo (mock data)

• Product film (3 min, mock data, figure design): storyboard in demo/video/STORYBOARD.md; record with node demo/video/record-segments.mjs (per-beat, concatenated) and cut the 60-second version with bash demo/video/cut-60s.sh demo/video/out/film-cut.mp4.
• Product demo (< 2 min, narrated): script demo/video/promo/SCRIPT.md, shots in demo/video/promo/edl/*.json; node demo/video/promo/tts.mjs 1.12 (Kokoro af_heart, one take per sentence), node demo/video/promo/cards/render.mjs (animated title/end cards), node demo/video/promo/build.mjs (writes the cut length to work/total.txt), node demo/video/promo/gen-audio.mjs (music bed sized to the cut, normalize to work/music.wav with loudnorm=I=-18), then build.mjs again → demo/video/out/promo.mp4. README hero and the autoplaying preview: node docs/img/src/render.mjs.

API

Endpoint overview

Group	Endpoints
Health / usage	GET /api/health, GET /api/usage
Projects (master)	/api/projects — create/list, messages, uploads (multipart file), design, design/draft, design/{v}/approve, deploy, agents, council
Evolution	/api/evolution — start, runs/{id}, runs/{id}/stop, {goalId}/tree, {goalId}/decisions, {goalId}/final, {goalId}/objectives
Task board	/api/tasks/{boardId} — items, events, start/complete/fail/strike-replace, conversation, restructure, archive-completed
Decisions	/api/decisions — pending user decisions and answers
Safety	/api/safety — policy, settings, safety-officer chat
Monitoring	/api/monitor — spans/events and SSE stream
Memory / workspace	GET /api/memory/graph, GET /api/workspace/files, GET /api/workspace/file
Canvas / agents	GET /api/canvas/{projectId}, GET /api/agents/{id}, GET /api/agents/{id}/genomes
Knowledge	/api/knowledge/skills, /api/knowledge/seed-status — platform manual + general skills seeded as notes
Devices	/api/devices — register, access (safety + user consent), commands; mock lab instruments
Safety incidents	/api/safety/incidents, /api/safety/halt/{projectId} (+ resume, decide)
UI	/api/ui/theme, /api/ui/layout (achromatic, safety-reviewed), /api/ui-extensions, /api/visual icons
People / cluster	/api/researchers, /api/cluster/nodes, /api/cluster/clients

Safety model

• Every self-modification (genome, prompt, lab tool, topology, mutation) passes the SafetyGate: hard-coded rules, then a Jev pre-screen, then an LLM review; protected paths cannot be edited by agents.
• Only the master agent can create or edit agents (AgentFactory).
• The referee locks criteria before deployment and keeps held-out tasks in its own store; agents never see them and the referee shares no memory with agents. Favoritism is monitored.
• Code runs only in Docker sandboxes (python:3.12-slim) with timeouts; workspaces are path-confined.
• All changes are audited (RevisionLog, soft delete) and every LLM/tool call is traced via MonitorBus.

Built during the hackathon

All code in this repository was written on 2026-10-17 during The Recursive Agents Hackathon (Cerebral Valley × Crusoe). Third-party components: Spring Boot, MySQL, Qdrant, Caffeine, networknt json-schema-validator, Resilience4j, jSerialComm, the Docker python:3.12-slim image, Genomic Benchmarks data (Apache-2.0, Grešová et al. 2023); frontend: React, Vite, @xyflow/react, zustand, elkjs, react-force-graph-3d, @fontsource (Source Serif 4, IBM Plex); design skills vendored in .claude/skills/ (hairline, taste-skill, MIT).

📚 Credits and citations

Team: Ziyuan Yan, Fanchao Yu.

Applied use case: a project of Kwon Lab, Northeastern University — PI Prof. MiYoung Kwon; Ziyuan Yan is a graduate researcher in the lab. The mock data parameters in the low-vision demo are drawn from these papers (every other number is synthetic; see docs/references.md):

• Liu, R., & Kwon, M. (2016). Integrating oculomotor and perceptual training to induce a pseudofovea: A model system for studying central vision loss. Journal of Vision, 16(6):10, 1–21. https://doi.org/10.1167/16.6.10
• Yu, H., Shamsi, F., & Kwon, M. (2022). Altered eye movements during reading under degraded viewing conditions: Background luminance, text blur, and text contrast. Journal of Vision, 22(10):4, 1–20. https://doi.org/10.1167/jov.22.10.4
• Yu, H., & Kwon, M. (2023). Altered eye movements during reading with simulated central and peripheral visual field defects. Investigative Ophthalmology & Visual Science, 64(13):21. https://doi.org/10.1167/iovs.64.13.21

Sponsors: NVIDIA Nemotron, Crusoe Managed Inference, You.com. Hackathon: The Recursive Agents Hackathon (Cerebral Valley × Crusoe, October 17, 2026).