Skip to content

AGENTS.md

Latest commit

 

History

History
133 lines (92 loc) · 4.69 KB

AGENTS.md

File metadata and controls

133 lines (92 loc) · 4.69 KB
Raw

AGENTS.md - Architecture Documentation

Requirements

  • Node.js: v24+ required
    • On macOS with Homebrew: export PATH="/opt/homebrew/opt/node@24/bin:$PATH"

Commands

  • Run CLI: npx tsx src/srchd.ts
  • Type checking: npm run typecheck
  • Linting: npm run lint
  • Database migrations: npx drizzle-kit generate && npx drizzle-kit migrate

Architecture Overview

srchd orchestrates AI agents through a publication/review system. Agents collaborate to solve complex problems by publishing papers, reviewing each other's work, and citing relevant publications.

Core Components

Database Layer (src/db/)

ORM: Drizzle ORM with SQLite backend (./db.sqlite)

Schema Entities:

  • experiments - Experiment metadata with unique names and problem statements
  • agents - AI agents with model, provider, thinking config, and tools
  • evolutions - System prompt evolution history for self-improvement
  • messages - Agent conversation history with position tracking
  • publications - Research papers with status (SUBMITTED/PUBLISHED/REJECTED)
  • citations - Citation relationships between publications
  • reviews - Peer reviews with grades (STRONG_ACCEPT/ACCEPT/REJECT/STRONG_REJECT)
  • solutions - Tracked solutions with reasoning and publication references
  • token_usages - Token usage tracking for cost monitoring

Key Data Relationships:

  • Experiments contain multiple agents
  • Agents have memories and can author publications
  • Publications can cite other publications within experiments
  • Publications undergo peer review by agents
  • All entities maintain created/updated timestamps

CLI Interface (src/srchd.ts)

Built with Commander.js, provides commands for:

  • Experiment management (create, list, metrics)
  • Agent management (create, list, evolve, run)
  • Computer image building
  • Web UI server

Agent Profile System (src/agent_profile.ts)

Profiles define pre-configured agent types in agents/<profile-name>/:

  • prompt.md - System prompt defining behavior and objectives
  • settings.json - Tools, environment variables, Docker image name
  • Dockerfile (optional) - Custom Docker environment for computer-use agents

Available profiles: research, security, arc-agi, code, formal-math, browse, security-browse

Tools System (src/tools/)

Agents interact via MCP servers:

Core Tools (always available):

  • publications - Search, submit, review publications
  • system_prompt_self_edit - Get/update system prompt for self-improvement
  • goal_solution - Get/advertise best solution

Optional Tools (per profile):

  • computer - Execute commands, read/write files in Kubernetes pod
  • web - Search and scrape web content

Models System (src/models/)

Supported providers: Anthropic, OpenAI, Google, Mistral, Moonshot AI, Deepseek

Thinking levels: none, low, high

Runner System (src/runner/)

Orchestrates tick-based agent execution:

  1. Load evolution (system prompt) and message history
  2. Create LLM with model + thinking config
  3. Connect MCP tool servers
  4. LLM generates response with tool calls
  5. Execute tools and store results
  6. Record token usage
  7. Repeat until stopping condition

Computer System (src/computer/)

Manages Kubernetes pods for sandboxed agent execution:

  • Isolated pods per agent with custom Docker images
  • Persistent volumes for stateful work
  • File system access and command execution

Resources Layer (src/resources/)

Abstraction over database entities: ExperimentResource, AgentResource, PublicationResource, SolutionResource, TokenUsageResource, MessagesResource

Server/UI (src/server/)

Web server (Hono) providing experiment monitoring, publication browsing, citation graphs, and usage analytics.

Configuration

Environment Variables:

  • OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY
  • MISTRAL_API_KEY, MOONSHOT_API_KEY, DEEPSEEK_API_KEY
  • FIRECRAWL_API_KEY (optional, for web scraping)

TypeScript (tsconfig.json):

  • Strict mode enabled
  • ESM modules with CommonJS compilation target
  • Path aliases: @app/* → src/*

Database (drizzle.config.ts):

  • SQLite database with Drizzle migrations in src/migrations/

Extension Points

New Agent Profile: Create agents/<name>/ with prompt.md, settings.json, and optional Dockerfile

New Model Provider: Implement LLM interface in src/models/<provider>.ts, update provider.ts

New Tool: Create MCP server in src/tools/<tool>.ts, add to constants.ts, configure in profile

Performance & Security

  • Concurrent agent execution with cost tracking
  • Kubernetes pods isolate agent execution
  • Custom Docker images restrict available tools
  • API keys stored in environment only