Agent System

Agent System

A durable multi-agent orchestrator with:

• explicit run graphs and checkpoint/resume
• orchestrator-controlled parallel delegation
• bounded research swarm execution
• coding, review, repair, CI, and approval loops
• project memory in backing stores exposed through MCP resources and tools
• a real SQLite vector index for memory retrieval
• a pluggable external research backend with Tavily support

Scope

This implementation targets the MCP 2025-11-25 spec baseline with the official Python MCP SDK and a FastMCP server for the memory surface. For local development it runs over stdio. For remote deployment, see docs/remote_auth.md.

Layout

• app/runtime: run state, scheduler, orchestrator loop, checkpointing
• app/planner: planning and graph revision helpers
• app/agents: node executors for research, code, review, repair, CI, synthesis, approval
• app/memory: SQLite-backed memory, retrieval, and artifact index
• app/mcp_server: FastMCP resources, tools, prompts, and server entrypoint
• tests: acceptance and unit coverage

Local usage

uv sync --group dev
uv run pytest
uv run agent-system-mcp

Retrieval and research backends

• Memory entries are indexed into a local SQLite vector table using sqlite-vec.
• The default embedding provider is auto: it prefers a real sentence-transformers model and falls back to the deterministic hash provider only if the model cannot load.
• Research uses an in-memory corpus backend when a node provides inputs.corpus.
• If TAVILY_API_KEY is set, corpus-free research nodes can use the Tavily backend for external web research.
• If no corpus and no Tavily key are available, research returns bounded empty findings instead of inventing sources.

Embedding configuration

• AGENT_SYSTEM_EMBEDDING_PROVIDER=auto|sentence-transformers|hash
• AGENT_SYSTEM_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
• AGENT_SYSTEM_EMBEDDING_CACHE_DIR=/path/to/cache
• AGENT_SYSTEM_EMBEDDING_LOCAL_ONLY=true|false

Example:

AGENT_SYSTEM_EMBEDDING_PROVIDER=sentence-transformers uv run agent-system create-run "improve scheduler"

Local transport

Development uses the MCP stdio transport.

Remote deployment

Remote deployment is intentionally documentation-only in v1. The server documents an OAuth 2.1-compatible consent path and keeps local stdio as the default development mode.

Full documentation

• state.md: current project state, changes since creation, and roadmap
• docs/getting_started.md: fastest path to a working local run and MCP server
• docs/operator_guide.md: full system overview, operations, and best practices
• docs/developer_custom_graphs.md: Python API usage, custom graph design, and node payload reference
• docs/codex_mcp_usage.md: how Codex should use this MCP for large-app planning, memory, and checkpointed execution
• examples/plan_large_app.py: example of generating a large-app blueprint and run programmatically