How esinecan/skynet-agent works
Project Type and Purpose
• This is a full-stack, monolithic AI assistant system (“Skynet Agent”) implemented in TypeScript/Node.js (backend) with a React/Vite/Tailwind frontend (“client”).
• Purpose: Expose an HTTP API and web GUI to drive an autonomous agent that integrates with Google Gemini (LLM), manages semantic memory (Milvus or in-memory), performs multi-step reasoning and self-reflection, and invokes external tools via the Model Context Protocol (MCP).
High-Level File Structure Analysis
• Top-level “src/” holds the backend:
• agent/ (workflow, intrinsic motivation, LLM client, self-reflection, schemas)
• memory/ (Milvus or in-memory storage, consolidation cron)
• mcp/ (external tool client manager)
• server/ (Express API, streaming, file uploads)
• db/ (session persistence)
• utils/ (config loader, logger, error handler, health checks)
• run.ts / index.ts (bootstrap + CLI args)
• “client/” holds the React GUI:
• App.tsx, components (ChatInterface, InputArea, MessageList, SessionList)
• Zustand store for streaming chat
• Vite/Tailwind configuration
• Deployment & config: Dockerfile, docker-compose.yml, .env + config.json, scripts (start.sh, start.bat)
README Insights on Architecture
• Backend initializes: loads .env, logger, error handlers → agent → Express server
• Agent pipeline: receives text → LLM calls (Gemini) → memory lookup/store → optional self-reflection or intrinsic tasks → response
• MCP: dynamically loads tool servers (e.g., Playwright, filesystem, CLI) → orchestrated via LangGraph workflow
• Memory consolidation: cron job summarizing stored memories
• Frontend: React SPA served statically by Express in production; dev uses proxy to backend
Diagramming the System
• Frontend Web UI (React + Vite + Tailwind)
• API Layer (Express.js server)
• Agent Core (workflow, motivation, reflection modules)
• LLM Service (Google Gemini API)
• Memory Store (Milvus vector DB or in-memory fallback + file-based sessions storage)
• MCP Clients (Playwright, filesystem, CLI, etc.)
• Scheduler (Memory Consolidation cron)
• Persistent Storage (local ./data directories for sessions & fallback memory)
• External Services (Milvus container, MCP servers)
1. User → Web UI (HTTP / SSE) → Express API
2. API → Agent Core (“processQuery(query, sessionId)”)
3. Agent Core → LLM Service (REST/gRPC calls to Gemini)
4. Agent Core ↔ Memory Store (vector search, insert, consolidation)
5. Agent Core → MCP Clients (spawn tool processes via MCP protocol)
6. Agent Core → API (stream back partial/full responses SSE or JSON)
7. Scheduler → Memory Store (trigger consolidation)
8. API → Persistent Storage (sessions CRUD)
9. Docker / docker-compose orchestrates backend, Milvus, and optional front-end container
c. Architectural Patterns & Principles:
• Layered separation: UI ↔ API ↔ Core Agent ↔ External dependencies
• Orchestrator pattern: LangGraph driving multi-step workflows
• Adapter pattern: llmClient wraps Gemini API; milvus.ts wraps vector DB
• Failover: in-memory fallback if Milvus unavailable
• Plugin/extensibility: dynamic MCP server loading
d. Key Technologies & Libraries:
• Backend: Node.js, TypeScript, Express, Multer, Zod, ts-node-dev, Jest
• Agent: Google Gemini embedding & generation, LangGraph workflow, intrinsicMotivation module, selfReflection module
• Memory: @zilliz/milvus2-sdk-node, in-memory consolidation
• MCP: @modelcontextprotocol clients
• Frontend: React18, TypeScript, Vite, Tailwind CSS, Zustand, React Markdown, SSE
Detail & Precision
• Every module from the file tree is represented at least at the component level.
• Dynamic flows: memory consolidation cron path, MCP reload API.
• Fallback paths (in-memory vs. Milvus).
• Important configuration sources (.env, config.json, VS Code settings).